Article

Using Programmable Sample Positions

Configure the position of samples when rendering to a multisampled render target.

Overview

Traditional multisample anti-aliasing (MSAA) operations use fixed sample positions, defined by the GPU, that sample and resolve subpixels using the same pattern for all render passes.

Programmable sample positions unlock additional rendering techniques because they can be configured into custom patterns that can be reused or repositioned for any render pass.

The Subpixel Grid

Programmable sample positions are set on a 4-bit subpixel grid (16 x 16 subpixels). Floating-point values are in the [0.0, 1.0) range along each axis, with the origin (0, 0) defined at the top-left corner. Values can be set from 0/16 up to 15/16, inclusive, in 1/16 increments along each axis.

Coordinate system diagram showing the subpixel grid on which programmable sample positions are set. Example positions are set at the top-left corner (0, 0), top-right corner (1, 0), bottom-right corner (1, 1), bottom-left corner (0, 1), and center (0.5, 0.5).

Specifying Programmable Sample Positions

Programmable sample positions are defined as an array of MTLSamplePosition values. You set them by calling the setSamplePositions(_:count:) method of a MTLRenderPassDescriptor object.

static const MTLSamplePosition samplePositions[4] = {
    0.25, 0.25,
    0.75, 0.25,
    0.75, 0.75,
    0.25, 0.75,
};
[renderPassDescriptor setSamplePositions:samplePositions count:4];

The following grid shows the programmable sample positions in the samplePositions array:

Coordinate system diagram showing the subpixel grid on which programmable sample positions are set. Example positions are set at (0.25, 0.25), (0.75, 0.25), (0.75, 0.75), and (0.25, 0.75).

Querying Default Sample Positions

You can query sample positions for a specific sample count by calling the getDefaultSamplePositions(_:count:) method.

Default 1-sample Position

The following table and grid show the position index, values, and placement for the default 1-sample position.

Position index

Position values

0

0.5, 0.5

Coordinate system diagram showing the subpixel grid on which the default 1-sample position is set. The positions is set at (0.5, 0.5).

Default 2-sample Positions

The following table and grid show the position indices, values, and placements for the default 2-sample positions.

Position index

Position values

0

0.75, 0.75

1

0.25, 0.25

Coordinate system diagram showing the subpixel grid on which the default 2-sample positions are set. The positions are set at (0.25, 0.25) and (0.75, 0.75).

Default 4-sample Positions

The following table and grid show the position indices, values, and placements for the default 4-sample positions.

Position index

Position values

0

0.375, 0.125

1

0.875, 0.375

2

0.125, 0.625

3

0.625, 0.875

Coordinate system diagram showing the subpixel grid on which the default 4-sample positions are set. The positions are set at (0.375, 0.125), (0.875, 0.375), (0.125, 0.625), and (0.625, 0.875).

Default 8-sample Positions

The following table and grid show the position indices, values, and placements for the default 8-sample positions.

Position index

Position values

0

0.5625, 0.3125

1

0.4375, 0.6875

2

0.8125, 0.5625

3

0.3125, 0.1875

4

0.1875, 0.8125

5

0.0625, 0.4375

6

0.6875, 0.9375

7

0.9375, 0.0625

Coordinate system diagram showing the subpixel grid on which the default 8-sample positions are set. The positions are set at (0.5625, 0.3125), (0.4375, 0.6875), (0.8125, 0.5625), (0.3125, 0.1875), (0.1875, 0.8125), (0.0625, 0.4375), (0.6875, 0.9375) and (0.9375, 0.0625).

Support for Programmable Sample Positions

Support for programmable sample positions varies by device. You can query it by calling the areProgrammableSamplePositionsSupported property.

Additionally, the number of programmable sample positions supported (the number of elements in a MTLSamplePosition array) depends on the supported sample count. This value also varies by device; you can query it by calling the supportsTextureSampleCount(_:) method.

See Also

Programmable Sample Positions

Handling MSAA Depth with Programmable Sample Positions

Use depth render targets and programmable sample positions effectively.