Class TextureTensorData

Represents the data storage for a 'Tensor' as a render texture, for backends that use GPU pixel shaders.

Sentis packs the tensor data into the pixels of an RGBA float4 texture.

Sentis chooses a single tensor dimension as the blocked axis, across which data is chunked in float4 blocks.

Tensor dimensions don't map directly to texture dimensions. Sentis creates the texture with dimensions large enough to fit all the data and pixel shaders index the data based on both the tensor and texture dimensions (see example below).

Inheritance

object

TextureTensorData

Implements

ITensorData

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Unity.InferenceEngine

Assembly: Unity.InferenceEngine.dll

Syntax

[MovedFrom("Unity.Sentis")]
public class TextureTensorData : ITensorData, IDisposable

Constructors

TextureTensorData(DataType, TensorShape, int, bool)

Initializes and returns an instance of TextureTensorData with given shape and blocked axis. A RenderTexture is allocated to the correct size.

Declaration

public TextureTensorData(DataType dataType, TensorShape shape, int axis, bool clearOnInit = false)

Parameters

Type	Name	Description
DataType	dataType	The data type of the tensor.
TensorShape	shape	The (unblocked) shape of the tensor.
int	axis	The axis on which to block the shape.
bool	clearOnInit	Whether to zero the data on allocation. The default value is false.

Properties

backendType

The device backend (CPU, GPU compute, or GPU pixel) where the tensor data is stored.

Declaration

public BackendType backendType { get; }

Property Value

Type	Description
BackendType

Remarks

Returns CPU, GPUCompute, or GPUPixel. Use this to determine whether data is on CPU or GPU before calling Download<T>(int) or scheduling Jobs that access the buffer.

blockAxis

Returns the axis of the tensor which is blocked.

It is possible to block on negative axes by considering a tensor of shape (d0, d1 ... dn) as one of shape (1, 1, .... 1, d0, d1 ... dn).

Thus negative axis values do not count from the back of the shape as elsewhere.

Declaration

public int blockAxis { get; }

Property Value

Type	Description
int

blockedAxisDiv4RemainderMask

A 4 int mask with 1 or 0 in each component to indicate whether the last blocked slice along the blocked axis has a valid entry or not. eg. if dimAxis % 4 = ceil(dimAxis/4)*4 - dimAxis = 3, blockedAxisDiv4RemainderMask = {1, 1, 1, 0};

Declaration

public int[] blockedAxisDiv4RemainderMask { get; }

Property Value

Type	Description
int[]

blockedShape

Returns the shape of the tensor with the blocked axis divided by 4.

Declaration

public TensorShape blockedShape { get; }

Property Value

Type	Description
TensorShape

bufferAsTexture

Returns the backing texture storing the tensor data.

Declaration

public RenderTexture bufferAsTexture { get; }

Property Value

Type	Description
RenderTexture

dataType

Returns the data type of the associated tensor.

Declaration

public DataType dataType { get; }

Property Value

Type	Description
DataType

dimAxis

The size of the blocked axis in the original tensor shape (when not blocked).

Declaration

public int dimAxis { get; }

Property Value

Type	Description
int

dimAxisDiv4

The size of the blocked axis in the blocked tensor shape, i.e. dimAxisDiv4 = ceil(dimAxis / 4).

Declaration

public int dimAxisDiv4 { get; }

Property Value

Type	Description
int

maxCapacity

The maximum count of the stored data elements.

Declaration

public int maxCapacity { get; }

Property Value

Type	Description
int

shape

Returns the shape of the associated tensor.

Declaration

public TensorShape shape { get; }

Property Value

Type	Description
TensorShape

strideAxis

The size of the stride of the blocked axis.

Declaration

public int strideAxis { get; }

Property Value

Type	Description
int

widthMask

Returns the width of the texture - 1 for efficient masking in shaders.

Declaration

public int widthMask { get; }

Property Value

Type	Description
int

widthShift

Returns the power in the power of two width of the backing texture.

Declaration

public int widthShift { get; }

Property Value

Type	Description
int

Methods

CompleteAllPendingOperations()

Blocking call to make sure that internal data is correctly written to and available for CPU read back.

Declaration

public void CompleteAllPendingOperations()

Remarks

Call before reading data via Download<T>(int) or IsReadbackRequestDone() when Jobs or GPU operations may still be in progress. For CPU backends, this completes any scheduled Jobs. For GPU backends, this waits for any in-flight transfers.

Examples

Complete pending jobs, then download.

  cpuData.fence = job.Schedule(count, 64);
                                                                   worker.Schedule(inputTensor);
                                                                   cpuData.CompleteAllPendingOperations();
                                                                   var data = cpuData.Download<float>(count);

Dispose()

Disposes of the TextureTensorData and any associated memory.

Declaration

public void Dispose()

DownloadAsync<T>(int)

Awaitable contiguous block of data from internal storage.

Declaration

public Awaitable<NativeArray<T>> DownloadAsync<T>(int dstCount) where T : unmanaged

Parameters

Type	Name	Description
int	dstCount	The number of elements to copy.

Returns

Type	Description
Awaitable<NativeArray<T>>	An Awaitable_1 that resolves to a NativeArray_1 containing the copied data.

Type Parameters

Name	Description
T	The element type of the data (for example, float or int).

Remarks

Use this to download data without blocking the main thread. For GPU backends, the readback runs asynchronously. The returned array uses Temp. Dispose of it when finished.

Examples

Download without blocking the main thread.

var data = await tensorData.DownloadAsync<float>(count);
float value = data[0];
data.Dispose();

Download<T>(int)

Blocking call that returns a contiguous block of data from internal storage.

Declaration

public NativeArray<T> Download<T>(int dstCount) where T : unmanaged

Parameters

Type	Name	Description
int	dstCount	The number of elements to copy.

Returns

Type	Description
NativeArray<T>	A new NativeArray_1 containing the copied data.

Type Parameters

Name	Description
T	The element type of the data (for example, float or int).

Remarks

Blocks until the data is available. For GPU backends, this may trigger a synchronous readback. The returned array uses Temp. Dispose of it or use it within the same frame. Call CompleteAllPendingOperations() first if Jobs or GPU work may be pending.

Examples

Wait for operations, download data, and dispose the array.

  tensorData.CompleteAllPendingOperations();
                                                                                                                                                                                                                                                                                                                                                                                                                        var data = tensorData.Download<float>(count);
                                                                                                                                                                                                                                                                                                                                                                                                                        float value = data[0];
                                                                                                                                                                                                                                                                                                                                                                                                                        data.Dispose();

~TextureTensorData()

Finalizes the TextureTensorData.

Declaration

protected ~TextureTensorData()

IsReadbackRequestDone()

Checks if asynchronous readback request is done.

Declaration

public bool IsReadbackRequestDone()

Returns

Type	Description
bool	true if the readback has completed. Otherwise false.

Remarks

Use after calling ReadbackRequest() to poll for completion. When this returns true, the data is available for CPU access. For CPU backends, this completes any pending Job operations and returns true when ready.

Examples

Poll for readback completion, then download.

  tensorData.ReadbackRequest();
                                                                                                                                                                                               while (!tensorData.IsReadbackRequestDone())
                                                                                                                                                                                                   await Task.Yield();
                                                                                                                                                                                               var data = tensorData.Download<float>(count);

Pin(Tensor, int, bool)

Moves the tensor into GPU memory on the GPUPixel back end device.

Declaration

public static TextureTensorData Pin(Tensor X, int blockAxis, bool clearOnInit = false)

Parameters

Type	Name	Description
Tensor	X	The tensor to move to the compute backend.
int	blockAxis	Which axis to block the tensor shape on.
bool	clearOnInit	Whether to zero the data on pinning. The default value is false.

Returns

Type	Description
TextureTensorData	The pinned TextureTensorData.

ReadbackRequest()

Schedules asynchronous readback of the internal data.

Declaration

public void ReadbackRequest()

Remarks

For GPU backends, initiates a non-blocking transfer from device to CPU. Poll IsReadbackRequestDone() to check completion, then call Download<T>(int) to obtain the data. For CPU backends, this is a no-op; data is already on CPU.

Examples

Schedule async readback.

  tensorData.ReadbackRequest();
                                                      // Continue other work, then check IsReadbackRequestDone()

ReadbackRequestAsync()

Declaration

public Task<bool> ReadbackRequestAsync()

Returns

Type	Description
Task<bool>

ToString()

Returns a string that represents the TextureTensorData.

Declaration

public override string ToString()

Returns

Type	Description
string	The summary string of the TextureTensorData.

Overrides

object.ToString()

Upload<T>(NativeArray<T>, int)

Uploads a contiguous block of tensor data to internal storage.

Declaration

public void Upload<T>(NativeArray<T> data, int srcCount) where T : unmanaged

Parameters

Type	Name	Description
NativeArray<T>	data	The source data to copy.
int	srcCount	The number of elements to copy from data.

Type Parameters

Name	Description
T	The element type of the data (for example, float or int).

Remarks

Copies srcCount elements from data into the internal buffer. For GPU backends, this transfers data from CPU to the device. Call CompleteAllPendingOperations() before reading the uploaded data if other operations may be pending.

Examples

Upload data to backing storage and wait for completion.

  var data = new NativeArray<float>(256, Allocator.Temp);
                                                                                                                                                                                                                                                                                                                                                                                                                          // Fill data
                                                                                                                                                                                                                                                                                                                                                                                                                          tensorData.Upload(data, 256);
                                                                                                                                                                                                                                                                                                                                                                                                                          tensorData.CompleteAllPendingOperations();

Implements

ITensorData

IDisposable