Edit

Share via

DML_SLICE1_OPERATOR_DESC structure (directml.h)

  • Article

Extracts a single subregion (a "slice") of an input tensor.

The input window describes the bounds of the input tensor to consider in the slice. The window is defined using three values for each dimension.

  • The offset marks the beginning of the window in a dimension.
  • The size marks the extent of the window in a dimension. The end of the window in a dimension is offset + size - 1.
  • The stride indicates how to traverse the elements in a dimension.
    • The magnitude of the stride indicates how many elements to advance when copying within the window.
    • If a stride is positive, elements are copied starting at the beginning of the window in the dimension.
    • If a stride is negative, elements are copied starting at the end of the window in the dimension.

The following pseudo-code illustrates how elements are copied using the input window. Note how elements in a dimension are copied from start to end with a positive stride, and copied from end to start with a negative stride.

CopyStart = InputWindowOffsets
for dimension i in [0, DimensionCount - 1]:
    if InputWindowStrides[i] < 0:
        CopyStart[i] += InputWindowSizes[i] - 1 // start at the end of the window in this dimension

OutputTensor[OutputCoordinates] = InputTensor[CopyStart + InputWindowStrides * OutputCoordinates]

The input window mustn't be empty in any dimension, and the window mustn't extend beyond the dimensions of the input tensor (out-of-bounds reads aren't permitted). The window's size and strides effectively limit the number of elements that may be copied from each dimension i of the input tensor.

MaxCopiedElements[i] = 1 + (InputWindowSize[i] - 1) / InputWindowStrides[i]

The output tensor isn't required to copy all reachable elements within the window. The slice is valid so long as 1 <= OutputSizes[i] <= MaxCopiedElements[i].

Syntax

struct DML_SLICE1_OPERATOR_DESC {
  const DML_TENSOR_DESC *InputTensor;
  const DML_TENSOR_DESC *OutputTensor;
  UINT                  DimensionCount;
  const UINT            *InputWindowOffsets;
  const UINT            *InputWindowSizes;
  const INT             *InputWindowStrides;
};

Members

InputTensor

Type: const DML_TENSOR_DESC*

The tensor to extract slices from.

OutputTensor

Type: const DML_TENSOR_DESC*

The tensor to write the sliced data results to.

DimensionCount

Type: UINT

The number of dimensions. This field determines the size of the InputWindowOffsets, InputWindowSizes, and InputWindowStrides arrays. This value must match the DimensionCount of the input and output tensors. This value must be between 1 and 8, inclusively, starting from DML_FEATURE_LEVEL_3_0; earlier feature levels require a value of either 4 or 5.

InputWindowOffsets

Type: _Field_size_(DimensionCount) const UINT*

An array containing the beginning (in elements) of the input window in each dimension. Values in the array must satisfy the constraint InputWindowOffsets[i] + InputWindowSizes[i] <= InputTensor.Sizes[i]

InputWindowSizes

Type: _Field_size_(DimensionCount) const UINT*

An array containing the extent (in elements) of the input window in each dimension. Values in the array must satisfy the constraint InputWindowOffsets[i] + InputWindowSizes[i] <= InputTensor.Sizes[i]

InputWindowStrides

Type: _Field_size_(DimensionCount) const UINT*

An array containing the slice's stride along each dimension of the input tensor, in elements. The magnitude of the stride indicates how many elements to advance when copying within the input window. The sign of the stride determines if elements are copied starting at the beginning of the window (positive stride) or end of the window (negative stride). Strides may not be 0.

Examples

The following examples use this same input tensor.

InputTensor: (Sizes:{1, 1, 4, 4}, DataType:FLOAT32)
[[[[ 1,  2,  3,  4],
   [ 5,  6,  7,  8],
   [ 9, 10, 11, 12],
   [13, 14, 15, 16]]]]

Example 1. Strided slice with positive strides

InputWindowOffsets = {0, 0, 0, 1}
InputWindowSizes   = {1, 1, 4, 3}
InputWindowStrides = {1, 1, 2, 2}

OutputTensor: (Sizes:{1, 1, 2, 2}, DataType:FLOAT32)
[[[[ 2,  4],
   [10, 12]]]]

The copied elements are calculated as follows.

Output[0,0,0,0] = {0,0,0,1} + {1,1,2,2} * {0,0,0,0} = Input[{0,0,0,1}] = 2
Output[0,0,0,1] = {0,0,0,1} + {1,1,2,2} * {0,0,0,1} = Input[{0,0,0,3}] = 4
Output[0,0,1,0] = {0,0,0,1} + {1,1,2,2} * {0,0,1,0} = Input[{0,0,2,1}] = 10
Output[0,0,1,1] = {0,0,0,1} + {1,1,2,2} * {0,0,1,1} = Input[{0,0,2,3}] = 12

Example 2. Strided slice with negative strides

InputWindowOffsets = {0, 0, 0, 1}
InputWindowSizes   = {1, 1, 4, 3}
InputWindowStrides = {1, 1, -2, 2}

OutputTensor: (Sizes:{1, 1, 2, 2}, DataType:FLOAT32)
[[[[14, 16],
   [ 6,  8]]]]

Recall that dimensions with negative window strides start copying at the end of the input window for that dimension; this is done by adding InputWindowSize[i] - 1 to the window offset. Dimensions with a positive stride simply start at InputWindowOffset[i].

  • Axis 0 (+1 window stride) starts copying at InputWindowOffsets[0] = 0.
  • Axis 1 (+1 window stride) starts copying at InputWindowOffsets[1] = 0.
  • Axis 2 (-2 window stride) starts copying at InputWindowOffsets[2] + InputWindowSizes[0] - 1 = 0 + 4 - 1 = 3.
  • Axis 3 (+2 window stride) starts copying at InputWindowOffsets[3] = 1.

The copied elements are calculated as follows.

Output[0,0,0,0] = {0,0,3,1} + {1,1,-2,2} * {0,0,0,0} = Input[{0,0,3,1}] = 14
Output[0,0,0,1] = {0,0,3,1} + {1,1,-2,2} * {0,0,0,1} = Input[{0,0,3,3}] = 16
Output[0,0,1,0] = {0,0,3,1} + {1,1,-2,2} * {0,0,1,0} = Input[{0,0,1,1}] = 6
Output[0,0,1,1] = {0,0,3,1} + {1,1,-2,2} * {0,0,1,1} = Input[{0,0,1,3}] = 8

Remarks

This operator is similar to DML_SLICE_OPERATOR_DESC, but it differs in two important ways.

  • Slice strides may be negative, which allows reversing values along dimensions.
  • The input window sizes are not necessarily the same as the output tensor sizes.

Availability

This operator was introduced in DML_FEATURE_LEVEL_2_1.

Tensor constraints

InputTensor and OutputTensor must have the same DataType and DimensionCount.

Tensor support

DML_FEATURE_LEVEL_4_1 and above

Tensor Kind Supported dimension counts Supported data types
InputTensor Input 1 to 8 FLOAT64, FLOAT32, FLOAT16, INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8
OutputTensor Output 1 to 8 FLOAT64, FLOAT32, FLOAT16, INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8

DML_FEATURE_LEVEL_3_0 and above

Tensor Kind Supported dimension counts Supported data types
InputTensor Input 1 to 8 FLOAT32, FLOAT16, INT32, INT16, INT8, UINT32, UINT16, UINT8
OutputTensor Output 1 to 8 FLOAT32, FLOAT16, INT32, INT16, INT8, UINT32, UINT16, UINT8

DML_FEATURE_LEVEL_2_1 and above

Tensor Kind Supported dimension counts Supported data types
InputTensor Input 4 to 5 FLOAT32, FLOAT16, INT32, INT16, INT8, UINT32, UINT16, UINT8
OutputTensor Output 4 to 5 FLOAT32, FLOAT16, INT32, INT16, INT8, UINT32, UINT16, UINT8

Requirements

Requirement Value
Minimum supported client Windows 10 Build 20348
Minimum supported server Windows 10 Build 20348
Header directml.h