DML_SCATTER_ND_OPERATOR_DESC structure (directml.h)

Copies the whole input tensor to the output, then overwrites selected indices with corresponding values from the updates tensor. This operator performs the following pseudocode, where "..." represents a series of coordinates, with the exact behavior determined by the axis and indices size.

output = input
output[indices[...]] = updates[...]

If two output element indices overlap (which is invalid), there is no guarantee of which last write wins.

Syntax

struct DML_SCATTER_ND_OPERATOR_DESC {
  const DML_TENSOR_DESC *InputTensor;
  const DML_TENSOR_DESC *IndicesTensor;
  const DML_TENSOR_DESC *UpdatesTensor;
  const DML_TENSOR_DESC *OutputTensor;
  UINT                  InputDimensionCount;
  UINT                  IndicesDimensionCount;
};

Members

InputTensor

Type: const DML_TENSOR_DESC*

The tensor to read from.

IndicesTensor

Type: const DML_TENSOR_DESC*

A tensor containing the indices. The DimensionCount of this tensor must match InputTensor.DimensionCount. The last dimension of the IndicesTensor is actually the number of coordinates per index tuple, and it mustn't exceed InputTensor.DimensionCount. For example, an indices tensor of size {1,4,5,2} with IndicesDimensionCount = 3 means a 4x5 array of 2-value coordinate tuples that index into InputTensor.

Starting with DML_FEATURE_LEVEL_3_0, this operator supports negative index values when using a signed integral type with this tensor. Negative indices are interpreted as being relative to the end of the respective dimension. For example, an index of -1 refers to the last element along that dimension.

UpdatesTensor

Type: const DML_TENSOR_DESC*

A tensor containing the new values to replace the existing input values at the corresponding indices. The DimensionCount of this tensor must match InputTensor.DimensionCount. The expected UpdatesTensor.Sizes are the concatenation of the IndicesTensor.Sizes leading segments and InputTensor.Sizes trailing segment to yield the following.

indexTupleSize = IndicesTensor.Sizes[IndicesTensor.DimensionCount - 1]
UpdatesTensor.Sizes = [
    1...,
    IndicesTensor.Sizes[(IndicesTensor.DimensionCount - IndicesDimensionCount) .. (IndicesTensor.DimensionCount - 1)],
    InputTensor.Sizes[(InputTensor.DimensionCount - indexTupleSize) .. InputTensor.DimensionCount]
]

The dimensions are right-aligned, with leading 1 values prepended if needed to satisfy UpdatesTensor.DimensionCount.

Here's an example.

InputTensor.Sizes = [3,4,5,6,7]
InputDimensionCount = 5
IndicesTensor.Sizes = [1,1, 1,2,3]
IndicesDimensionCount = 3 // can be thought of as a [1,2] array of 3-coordinate tuples

// The [1,2] comes from the indices tensor (ignoring last dimension, which is the tuple size),
// and the [6,7] comes from input tensor, ignoring the first 3 dimensions
// since the index tuples are 3 elements (from the indices tensor last dimension).
UpdatesTensor.Sizes = [1, 1,2,6,7]

OutputTensor

Type: const DML_TENSOR_DESC*

The tensor to write the results to. The Sizes and DataType of this tensor must match InputTensor.Sizes.

InputDimensionCount

Type: UINT

The number of actual input dimensions within the InputTensor after ignoring any irrelevant leading ones, ranging [1, InputTensor.DimensionCount). For example, given InputTensor.Sizes = {1,1,4,6} and InputDimensionCount = 3, the actual meaningful indices are {1,4,6}.

IndicesDimensionCount

Type: UINT

The number of actual index dimensions within the IndicesTensor after ignoring any irrelevant leading ones, ranging [1, IndicesTensor.DimensionCount). For example, given IndicesTensor.Sizes = {1,1,4,6} and IndicesDimensionCount = 3, the actual meaningful indices are {1,4,6}.

Examples

InputTensor: (Sizes:{8}, DataType:FLOAT32)
    [1, 2, 3, 4, 5, 6, 7, 8]

IndicesTensor: (Sizes:{4,1}, DataType:FLOAT32)
    [[4], [3], [1], [7]]

UpdatesTensor: (Sizes:{4}, DataType:FLOAT32)
    [9, 10, 11, 12]

// output = input
// output[indices[x, 0]] = updates[x]
OutputTensor: (Sizes:{8}, DataType:FLOAT32)
    [1, 11, 3, 10, 9, 6, 7, 12]

Availability

This operator was introduced in DML_FEATURE_LEVEL_2_1.

Tensor constraints

• IndicesTensor, InputTensor, OutputTensor, and UpdatesTensor must have the same DimensionCount.
• InputTensor, OutputTensor, and UpdatesTensor must have the same DataType.

Tensor support

DML_FEATURE_LEVEL_4_1 and above

DML_FEATURE_LEVEL_3_0 and above

DML_FEATURE_LEVEL_2_1 and above

Requirements