Struct MTLCompileOptions

Source

pub struct MTLCompileOptions { /* private fields */ }

Available on crate feature MTLLibrary only.

Expand description

Apple’s documentation

Implementations§

Source §

impl MTLCompileOptions

Source

pub fn preprocessorMacros( &self, ) -> Option<Retained<NSDictionary<NSString, NSObject>>>

List of preprocessor macros to consider to when compiling this program. Specified as key value pairs, using a NSDictionary. The keys must be NSString objects and values can be either NSString or NSNumber objects.

The default value is nil.

Source

pub unsafe fn setPreprocessorMacros( &self, preprocessor_macros: Option<&NSDictionary<NSString, NSObject>>, )

Setter for preprocessorMacros.

This is copied when set.

§Safety

preprocessor_macros generic should be of the correct type.

Source

pub fn fastMathEnabled(&self) -> bool

👎Deprecated: Use mathMode instead

If YES, enables the compiler to perform optimizations for floating-point arithmetic that may violate the IEEE 754 standard. It also enables the high precision variant of math functions for single precision floating-point scalar and vector types. fastMathEnabled defaults to YES.

Source

pub fn setFastMathEnabled(&self, fast_math_enabled: bool)

👎Deprecated: Use mathMode instead

Setter for fastMathEnabled.

Source

pub fn mathMode(&self) -> MTLMathMode

Sets the floating-point arithmetic optimizations. Default depends on the language standard version.

Source

pub fn setMathMode(&self, math_mode: MTLMathMode)

Setter for mathMode.

Source

pub fn mathFloatingPointFunctions(&self) -> MTLMathFloatingPointFunctions

Sets the default math functions for single precision floating-point. Default is MTLMathFloatingPointFunctionsFast.

Source

pub fn setMathFloatingPointFunctions( &self, math_floating_point_functions: MTLMathFloatingPointFunctions, )

Setter for mathFloatingPointFunctions.

Source

pub fn languageVersion(&self) -> MTLLanguageVersion

set the metal language version used to interpret the source.

Source

pub fn setLanguageVersion(&self, language_version: MTLLanguageVersion)

Setter for languageVersion.

Source

pub fn libraryType(&self) -> MTLLibraryType

Which type the library should be compiled as. The default value is MTLLibraryTypeExecutable.

MTLLibraryTypeExecutable is suitable to build a library of “kernel”, “vertex” and “fragment” qualified functions. MTLLibraryType is suitable when the compilation result will instead be used to instantiate a MTLDynamicLibrary. MTLDynamicLibrary contains no qualified functions, but it’s unqualified functions and variables can be used as an external dependency for compiling other libraries.

Source

pub fn setLibraryType(&self, library_type: MTLLibraryType)

Setter for libraryType.

Source

pub fn installName(&self) -> Option<Retained<NSString>>

The install name of this dynamic library.

The install name is used when a pipeline state is created that depends, directly or indirectly, on a dynamic library. The installName is embedded into any other MTLLibrary that links against the compilation result. This property should be set such that the dynamic library can be found in the file system at the time a pipeline state is created. Specify one of:

an absolute path to a file from which the dynamic library can be loaded, or
a path relative to @ executable_path, where @ executable_path is substituted with the directory name from which the MTLLibrary containing the MTLFunction entrypoint used to create the pipeline state is loaded, or
a path relative to @ loader_path, where @ loader_path is substituted with the directory name from which the MTLLibrary with the reference to this installName embedded is loaded. The first is appropriate for MTLDynamicLibrary written to the file-system using its serializeToURL:error: method on the current device. The others are appropriate when the MTLDynamicLibrary is installed as part of a bundle or app, where the absolute path is not known. This property is ignored when the type property is not set to MTLLibraryTypeDynamic. This propery should not be null if the property type is set to MTLLibraryTypeDynamic: the compilation will fail in that scenario.

Source

pub fn setInstallName(&self, install_name: Option<&NSString>)

Setter for installName.

This is copied when set.

Source

pub fn libraries( &self, ) -> Option<Retained<NSArray<ProtocolObject<dyn MTLDynamicLibrary>>>>

Available on crate feature MTLDynamicLibrary only.

A set of MTLDynamicLibrary instances to link against. The installName of the provided MTLDynamicLibrary is embedded into the compilation result. When a function from the resulting MTLLibrary is used (either as an MTLFunction, or as an to create a pipeline state, the embedded install names are used to automatically load the MTLDynamicLibrary instances. This property can be null if no libraries should be automatically loaded, either because the MTLLibrary has no external dependencies, or because you will use preloadedLibraries to specify the libraries to use at pipeline creation time.

Source

pub fn setLibraries( &self, libraries: Option<&NSArray<ProtocolObject<dyn MTLDynamicLibrary>>>, )

Available on crate feature MTLDynamicLibrary only.

Setter for libraries.

This is copied when set.

Source

pub fn preserveInvariance(&self) -> bool

If YES, set the compiler to compile shaders to preserve invariance. The default is false.

Source

pub fn setPreserveInvariance(&self, preserve_invariance: bool)

Setter for preserveInvariance.

Source

pub fn optimizationLevel(&self) -> MTLLibraryOptimizationLevel

Sets the compiler optimization level.

Source

pub fn setOptimizationLevel( &self, optimization_level: MTLLibraryOptimizationLevel, )

Setter for optimizationLevel.

Source

pub fn compileSymbolVisibility(&self) -> MTLCompileSymbolVisibility

Adds a compiler command to force the default visibility of symbols to be hidden

Source

pub fn setCompileSymbolVisibility( &self, compile_symbol_visibility: MTLCompileSymbolVisibility, )

Setter for compileSymbolVisibility.

Source

pub fn allowReferencingUndefinedSymbols(&self) -> bool

Adds a compiler command to allow the reference of undefined symbols

Source

pub fn setAllowReferencingUndefinedSymbols( &self, allow_referencing_undefined_symbols: bool, )

Setter for allowReferencingUndefinedSymbols.

Source

pub fn maxTotalThreadsPerThreadgroup(&self) -> NSUInteger

Adds a compiler command to specify the total threads per threadgroup

Source

pub fn setMaxTotalThreadsPerThreadgroup( &self, max_total_threads_per_threadgroup: NSUInteger, )

Setter for maxTotalThreadsPerThreadgroup.

Source

pub fn requiredThreadsPerThreadgroup(&self) -> MTLSize

Available on crate feature MTLTypes only.

Sets the required threads-per-threadgroup during dispatches. The threadsPerThreadgroup argument of any dispatch must match this value if it is set. Optional, unless the pipeline is going to use CooperativeTensors in which case this must be set. Setting this to a size of 0 in every dimension disables this property

Source

pub fn setRequiredThreadsPerThreadgroup( &self, required_threads_per_threadgroup: MTLSize, )

Available on crate feature MTLTypes only.

Setter for requiredThreadsPerThreadgroup.

Source

pub fn enableLogging(&self) -> bool

If YES, set the compiler to enable any logging in the shader. The default is false.

Source

pub fn setEnableLogging(&self, enable_logging: bool)

Setter for enableLogging.

Source §

impl MTLCompileOptions

Methods declared on superclass NSObject.

Source

pub fn init(this: Allocated<Self>) -> Retained<Self>

Source

pub fn new() -> Retained<Self>

Methods from Deref<Target = NSObject>§

Source

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>§

Source

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

§Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

§Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

Source

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T
where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

§Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

Source

pub fn downcast_ref<T>(&self) -> Option<&T>
where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

§Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

§Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

§Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

§Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}