Enumeration

MPSKernelOptions

The options used when creating a kernel.

Declaration

typedef enum MPSKernelOptions : NSUInteger {
    ...
} MPSKernelOptions;

Overview

The Metal Performance Shaders framework uses the same API validation layer that Metal uses to alert you to API mistakes during development. While this option is turned on in your Xcode scheme, common programming errors will either trigger an assert or send a warning to the debug log. Except in the case of serious errors, little or no output should arrive in the console under standard usage. You can set a kernel’s options parameter to the MPSKernelOptionsSkipAPIValidation value to skip most of this checking. This flag may also lead to small reductions in CPU cost.

Topics

Constants

MPSKernelOptionsNone

The default option for the kernel. Kernels created with this option will not skip any API validation and will not use reduced precision.

MPSKernelOptionsSkipAPIValidation

Most kernels will sanity check their arguments. This has a small but non-zero CPU cost. Setting this option, however, does not skip checks for memory allocation failure. Turning on this option can result in undefined behavior if the requested operation cannot be completed for some reason. Most error states will be passed through to Metal, which may do nothing or abort the program if Metal API validation is turned on.

MPSKernelOptionsAllowReducedPrecision

When possible, kernels use a higher-precision data representation internally than the destination storage format to avoid excessive accumulation of computational rounding error in the result. This option advises the kernel that the destination storage format already has too much precision for what is ultimately required downstream, and the kernel may use reduced precision internally when it determines that a less precise result would yield better performance. When enabled, the performance win is often small and the precision of the result may vary by hardware and OS.

MPSKernelOptionsDisableInternalTiling

Some kernels may automatically split up their work internally into multiple tiles. This improves performance on larger textures and reduces the amount of memory needed by the framework for temporary storage. However, if you are using your own tiling scheme to achieve similar results, your tile sizes and the framework’s choice of tile sizes may interfere with one another, causing the framework to subdivide your tiles for its own use inefficiently. Use this option to force the framework to process your data tile as a single chunk.

MPSKernelOptionsInsertDebugGroups

Enabling this option will cause various kernel encode methods to call the pushDebugGroup: and popDebugGroup methods. The debug string will be drawn from the kernel’s label property, if available, or the name of the class otherwise.

See Also

Properties

options

The set of options used to run the kernel.

device

The device on which the kernel will be used.

label

The string that identifies the kernel.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software