apple.metal.protocol

Interface MTLRasterizationRateMap

public interface MTLRasterizationRateMap

[@protocol] MTLRasterizationRateMap

Compiled read-only object that determines how variable rasterization rate is applied when rendering.

A variable rasterization rate map is compiled by MTLDevice from a MTLRasterizationRateMapDescriptor containing one or more MTLRasterizationRateLayerDescriptor. During compilation, the quality samples provided in the MTLRasterizationRateLayerDescriptor may be rounded up to the nearest supported value or granularity, depending on hardware support. However, the compilation will never round values down, so the actual rasterization will always happen at a quality level matching or exceeding the provided quality samples. During rasterization using the MTLRasterizationRateMap the screen space rendering is stored in a smaller area of the framebuffer, such that lower quality regions will not occupy as many texels as higher quality regions. The quality will never exceed 1:1 in any region of screen space. Because a smaller area of the framebuffer is populated, less fragment shader invocations are required to render content, and less bandwidth is consumed to store the shaded values. Use a rasterization rate map to reduce rendering quality in less-important or less-sampled regions of the framebuffer, such as the periphery of a VR/AR display or a far-away cascade of a shadow map.

Method Summary

Modifier and Type	Method and Description
void	copyParameterDataToBufferOffset(MTLBuffer buffer, long offset) copyParameterDataToBuffer:offset:
MTLDevice	device() [@property] device
java.lang.String	label() [@property] label
long	layerCount() [@property] layerCount
MTLSamplePosition	mapPhysicalToScreenCoordinatesForLayer(MTLSamplePosition physicalCoordinates, long layerIndex) mapPhysicalToScreenCoordinates:forLayer:
MTLSamplePosition	mapScreenToPhysicalCoordinatesForLayer(MTLSamplePosition screenCoordinates, long layerIndex) mapScreenToPhysicalCoordinates:forLayer:
MTLSizeAndAlign	parameterBufferSizeAndAlign() [@property] parameterBufferSizeAndAlign
MTLSize	physicalGranularity() [@property] physicalGranularity
MTLSize	physicalSizeForLayer(long layerIndex) getPhysicalSizeForLayer:
MTLSize	screenSize() [@property] screenSize

Method Detail

copyParameterDataToBufferOffset

void copyParameterDataToBufferOffset(MTLBuffer buffer,
                                     long offset)

copyParameterDataToBuffer:offset:

Copy the parameter data into the provided buffer at the provided offset.

The buffer must have storageMode MTLStorageModeShared, and a size of at least parameterBufferSizeAndAlign.size + offset. The specified offset must be a multiple of parameterBufferSize.align. The buffer can be bound to a shader stage to map screen space to physical fragment space, or vice versa.

device

MTLDevice device()

[@property] device

Returns:

The device on which the rasterization rate map was created

label

java.lang.String label()

[@property] label

A string to help identify this object.

layerCount

long layerCount()

[@property] layerCount

Different render-target layers may target different variable rasterization configurations. The rasterization rate layer for a primitive is selected on the [[render_target_layer_index]].

Returns:

The number of different configured layers in the rasterization map.

mapPhysicalToScreenCoordinatesForLayer

MTLSamplePosition mapPhysicalToScreenCoordinatesForLayer(MTLSamplePosition physicalCoordinates,
                                                         long layerIndex)

mapPhysicalToScreenCoordinates:forLayer:

Computes where an offset relative to the top-left of the framebuffer, in physical pixels, would end up in screen space, in screen space pixels. The returned value is greater-or-equal the input value because the rasterization quality never exceeds 1:1 in any region.

mapScreenToPhysicalCoordinatesForLayer

MTLSamplePosition mapScreenToPhysicalCoordinatesForLayer(MTLSamplePosition screenCoordinates,
                                                         long layerIndex)

mapScreenToPhysicalCoordinates:forLayer:

Computes where an offset relative to the top-left of screen space, in screen space pixels, would end up in the framebuffer, in physical fragments. The returned value is less-or-equal the input value because the rasterization quality never exceeds 1:1 in any region.

parameterBufferSizeAndAlign

MTLSizeAndAlign parameterBufferSizeAndAlign()

[@property] parameterBufferSizeAndAlign

Returns the size and alignment requirements of the parameter buffer for this rate map.

The parameter data can be copied into a buffer with this size and alignment using copyParameterDataToBuffer:offset:

physicalGranularity

MTLSize physicalGranularity()

[@property] physicalGranularity

Rendering algorithms that use binning or tiling in screen space may want to determine the screen space bin size using this value. The depth component of the returned MTLSize is always 0.

Returns:

The granularity, in physical pixels, at which variable rasterization rate varies.

physicalSizeForLayer

MTLSize physicalSizeForLayer(long layerIndex)

getPhysicalSizeForLayer:

The dimensions, in physical fragments, of the area in the render target where variable rasterization is applied

Different configured layers may have a different rasterization rate and may have different size after rendering. The rasterization rate layer for a primitive is selected on the [[render_target_layer_index]].

screenSize

MTLSize screenSize()

[@property] screenSize

The region always has its origin at [0, 0]. The depth component of the returned MTLSize is always 0.

Returns:

The dimensions, in screen space pixels, of the region where variable rasterization is applied.