pub struct MPSInstanceAccelerationStructure { /* private fields */ }MPSAccelerationStructure and MPSCore and MPSInstanceAccelerationStructure and MPSKernel only.Expand description
An acceleration structure built over instances of other acceleration structures
Instancing can be used to reduce memory usage in scenes that contain many copies of the same object(s) or to combine multiple acceleration structures such as a static and dynamic acceleration structure into a two-level instance hierarchy.
The typical pattern for creating an instance acceleration structure is as follows. First, create individual bottom-level acceleration structures. Then assign these acceleration structures to the accelerationStructures property of an instance acceleration structure.
All of the acceleration structures in the instance hierarchy must share the same MPSAccelerationStructureGroup. Furthermore, all of the bottom-level acceleration structures must share the same vertex buffer, index buffer, etc. although they may have different offsets within those buffers.
MPSAccelerationStructureGroup *group = nil;
group = [[MPSAccelerationStructureGroup alloc] initWithDevice:device];
MPSInstanceAccelerationStructure *instanceAccel = nil;
instanceAccel = [[MPSInstanceAccelerationStructure alloc] initWithGroup:group];
NSMutableArray *accelerationStructures = [NSMutableArray array];
instanceAccel.accelerationStructures = accelerationStructures;
instanceAccel.instanceCount = instanceCount;
for (ObjectType *objectType in objectTypes) {
MPSTriangleAccelerationStructure *triAccel = nil;
triAccel = [[MPSTriangleAccelerationStructure alloc] initWithGroup:group];
triAccel.vertexBuffer = objectType.vertexBuffer;
triAccel.vertexBufferOffset = objectType.vertexBufferOffset;
triAccel.triangleCount = objectType.triangleCount;
[triAccel rebuild];
[accelerationStructures addObject:triAccel];
}Next, create a buffer containing the acceleration structure index for each instance, and another acceleration structure containing the transformation matrix for each instance:
NSUInteger instanceBufferLength = sizeof(uint32_t) * instanceCount;
id <MTLBuffer> instanceBuffer =
[device newBufferWithLength:instanceBufferLength
options:MTLResourceStorageModeManaged];
memcpy(instanceBuffer.contents, instances,
instanceBufferLength);
[instanceBuffer
didModifyRange:NSMakeRange(0, instanceBufferLength)];
instanceAccel.instanceBuffer = instanceBuffer;
// Similar for transformation matrix bufferFinally, rebuild the instance acceleration structure:
[instanceAccel rebuild];Refitting and Rebuilding Bottom-Level Acceleration Structures: when a bottom level acceleration structure is rebuild or refit, its’ bounding box may change. Therefore, the instance acceleration structure also needs to be rebuilt or refit.
Copying and Serializing Instance Acceleration Structures: When an instance acceleration structure is copied or serialized, the bottom level acceleration structures are not copied or serialized. These must be copied or serialized along with the instance acceleration structure and assigned to the new instance acceleration structure. This also applies to buffer properties such as the instance buffer, transformation buffer, etc.
Performance Guidelines:
-
Use instancing to reduce memory usage: if there are many copies of the same object(s) in a scene, using instances of the same object can reduce memory usage and acceleration structure build time. Rebuilding or refitting the top level acceleration structure can also be much faster than rebuilding a large single level acceleration structure.
-
Consider flattening your instance hierarchy into a single acceleration structure if the increased memory usage and acceleration structure build time are not a concern. Intersecting a two level acceleration structure can have a significant performance cost so only use it when necessary. Which technique to use depends on the scene and use case. For example, in a rendering application, it may be best to use an instance hierarchy for interactive scene editing and preview and flattening the instance hierarchy for the final render. For smaller scenes, it may also be sufficient to refit a flattened acceleration structure rather than rebuilding an instance hierarchy.
-
If there is only a single object in the scene, intersect its acceleration structure directly instead of using an instance hierarchy.
-
Consider dividing objects into static and dynamic acceleration structures. If dynamic objects require the acceleration structure to be rebuilt frequently, create a high quality static acceleration structure and a lower quality but faster to build dynamic acceleration structure. These two acceleration structures can then be combined with a two level acceleration structure. Use MPSTransformTypeIdentity to reduce the overhead of this technique. Whether this technique is more efficient than rebuilding the entire acceleration structure depends on the scene.
See MPSAccelerationStructure for more information
See also Apple’s documentation
Implementations§
Source§impl MPSInstanceAccelerationStructure
impl MPSInstanceAccelerationStructure
Sourcepub unsafe fn accelerationStructures(
&self,
) -> Option<Retained<NSArray<MPSPolygonAccelerationStructure>>>
👎DeprecatedAvailable on crate features MPSRayIntersector and MPSPolygonAccelerationStructure only.
pub unsafe fn accelerationStructures( &self, ) -> Option<Retained<NSArray<MPSPolygonAccelerationStructure>>>
MPSRayIntersector and MPSPolygonAccelerationStructure only.Acceleration structures available for use in this instance acceleration structure. Each instance must provide an index into this array in the instance buffer as well as a transformation matrix in the transform buffer. All acceleration structures must share a single vertex buffer, optional index buffer, and optional mask buffer, though they may have different offsets within each buffer, and all acceleration structures must share the same acceleration structure group. If a polygon acceleration structure is rebuilt or refit, the instance acceleration structure must subsequently be rebuilt or refit.
Sourcepub unsafe fn setAccelerationStructures(
&self,
acceleration_structures: Option<&NSArray<MPSPolygonAccelerationStructure>>,
)
👎DeprecatedAvailable on crate features MPSRayIntersector and MPSPolygonAccelerationStructure only.
pub unsafe fn setAccelerationStructures( &self, acceleration_structures: Option<&NSArray<MPSPolygonAccelerationStructure>>, )
MPSRayIntersector and MPSPolygonAccelerationStructure only.Setter for accelerationStructures.
Sourcepub unsafe fn instanceBuffer(
&self,
) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn instanceBuffer( &self, ) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
MPSRayIntersector only.Buffer containing the 32 bit unsigned integer index into the acceleration structure array for each instance
Sourcepub unsafe fn setInstanceBuffer(
&self,
instance_buffer: Option<&ProtocolObject<dyn MTLBuffer>>,
)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setInstanceBuffer( &self, instance_buffer: Option<&ProtocolObject<dyn MTLBuffer>>, )
MPSRayIntersector only.Setter for instanceBuffer.
§Safety
instance_buffermay need to be synchronized.instance_buffermay be unretained, you must ensure it is kept alive while in use.instance_buffercontents should be of the correct type.
Sourcepub unsafe fn instanceBufferOffset(&self) -> NSUInteger
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn instanceBufferOffset(&self) -> NSUInteger
MPSRayIntersector only.Offset, in bytes, into the instance buffer. Defaults to 0 bytes. Must be aligned to 4 bytes.
Sourcepub unsafe fn setInstanceBufferOffset(&self, instance_buffer_offset: NSUInteger)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setInstanceBufferOffset(&self, instance_buffer_offset: NSUInteger)
MPSRayIntersector only.Setter for instanceBufferOffset.
Sourcepub unsafe fn transformBuffer(
&self,
) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn transformBuffer( &self, ) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
MPSRayIntersector only.Buffer containing one column major matrix_float4x4 transformation matrix per instance
Sourcepub unsafe fn setTransformBuffer(
&self,
transform_buffer: Option<&ProtocolObject<dyn MTLBuffer>>,
)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setTransformBuffer( &self, transform_buffer: Option<&ProtocolObject<dyn MTLBuffer>>, )
MPSRayIntersector only.Setter for transformBuffer.
§Safety
transform_buffermay need to be synchronized.transform_buffermay be unretained, you must ensure it is kept alive while in use.transform_buffercontents should be of the correct type.
Sourcepub unsafe fn transformBufferOffset(&self) -> NSUInteger
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn transformBufferOffset(&self) -> NSUInteger
MPSRayIntersector only.Offset, in bytes, into the transform buffer. Defaults to 0 bytes. Must be aligned to the stride of the transform type.
Sourcepub unsafe fn setTransformBufferOffset(
&self,
transform_buffer_offset: NSUInteger,
)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setTransformBufferOffset( &self, transform_buffer_offset: NSUInteger, )
MPSRayIntersector only.Setter for transformBufferOffset.
Sourcepub unsafe fn transformType(&self) -> MPSTransformType
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn transformType(&self) -> MPSTransformType
MPSRayIntersector only.Instance transform type. Defaults to MPSTransformTypeFloat4x4. Changes to this property require rebuilding the acceleration structure.
Sourcepub unsafe fn setTransformType(&self, transform_type: MPSTransformType)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setTransformType(&self, transform_type: MPSTransformType)
MPSRayIntersector only.Setter for transformType.
Sourcepub unsafe fn maskBuffer(
&self,
) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn maskBuffer( &self, ) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
MPSRayIntersector only.Mask buffer containing one uint32_t mask per instance. May be nil.
Sourcepub unsafe fn setMaskBuffer(
&self,
mask_buffer: Option<&ProtocolObject<dyn MTLBuffer>>,
)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setMaskBuffer( &self, mask_buffer: Option<&ProtocolObject<dyn MTLBuffer>>, )
MPSRayIntersector only.Setter for maskBuffer.
§Safety
mask_buffermay need to be synchronized.mask_buffermay be unretained, you must ensure it is kept alive while in use.mask_buffercontents should be of the correct type.
Sourcepub unsafe fn maskBufferOffset(&self) -> NSUInteger
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn maskBufferOffset(&self) -> NSUInteger
MPSRayIntersector only.Offset, in bytes, into the mask buffer. Defaults to 0 bytes. Must be aligned to 4 bytes.
Sourcepub unsafe fn setMaskBufferOffset(&self, mask_buffer_offset: NSUInteger)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setMaskBufferOffset(&self, mask_buffer_offset: NSUInteger)
MPSRayIntersector only.Setter for maskBufferOffset.
Sourcepub unsafe fn instanceCount(&self) -> NSUInteger
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn instanceCount(&self) -> NSUInteger
MPSRayIntersector only.Number of instances. Changes to this property require rebuilding the acceleration structure.
Sourcepub unsafe fn setInstanceCount(&self, instance_count: NSUInteger)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setInstanceCount(&self, instance_count: NSUInteger)
MPSRayIntersector only.Setter for instanceCount.
Source§impl MPSInstanceAccelerationStructure
Methods declared on superclass MPSAccelerationStructure.
impl MPSInstanceAccelerationStructure
Methods declared on superclass MPSAccelerationStructure.
pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>
MPSRayIntersector only.Sourcepub unsafe fn initWithDevice(
this: Allocated<Self>,
device: &ProtocolObject<dyn MTLDevice>,
) -> Retained<Self>
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn initWithDevice( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, ) -> Retained<Self>
MPSRayIntersector only.Initialize the acceleration structure with a Metal device
Sourcepub unsafe fn initWithCoder_device(
this: Allocated<Self>,
a_decoder: &NSCoder,
device: &ProtocolObject<dyn MTLDevice>,
) -> Option<Retained<Self>>
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn initWithCoder_device( this: Allocated<Self>, a_decoder: &NSCoder, device: &ProtocolObject<dyn MTLDevice>, ) -> Option<Retained<Self>>
MPSRayIntersector only.Initialize the acceleration structure with an NSCoder and a Metal device. Buffer properties such as the vertex buffer, instance buffer, etc. are set to nil. Encode and decode these buffers along with the acceleration structure instead.
§Safety
a_decoder possibly has further requirements.
Sourcepub unsafe fn initWithGroup(
this: Allocated<Self>,
group: &MPSAccelerationStructureGroup,
) -> Retained<Self>
👎DeprecatedAvailable on crate features MPSRayIntersector and MPSAccelerationStructureGroup only.
pub unsafe fn initWithGroup( this: Allocated<Self>, group: &MPSAccelerationStructureGroup, ) -> Retained<Self>
MPSRayIntersector and MPSAccelerationStructureGroup only.Initialize the acceleration structure with an acceleration structure group, if the acceleration structure will be used in an instance hierarchy.
The Metal device is determined from the acceleration structure group. All acceleration structures in the instance hierarchy must share the same group.
Sourcepub unsafe fn initWithCoder_group(
this: Allocated<Self>,
a_decoder: &NSCoder,
group: &MPSAccelerationStructureGroup,
) -> Option<Retained<Self>>
👎DeprecatedAvailable on crate features MPSRayIntersector and MPSAccelerationStructureGroup only.
pub unsafe fn initWithCoder_group( this: Allocated<Self>, a_decoder: &NSCoder, group: &MPSAccelerationStructureGroup, ) -> Option<Retained<Self>>
MPSRayIntersector and MPSAccelerationStructureGroup only.Initialize the acceleration structure with an NSCoder and an acceleration structure group, if the acceleration structure will be used in an instance hierarchy. All acceleration structures in the instance hierarchy must share the same group. Buffer properties such as the vertex buffer, instance buffer, etc. are set to nil. Encode and decode these buffers along with the acceleration structure instead.
§Safety
a_decoder possibly has further requirements.
Source§impl MPSInstanceAccelerationStructure
Methods declared on superclass MPSKernel.
impl MPSInstanceAccelerationStructure
Methods declared on superclass MPSKernel.
Sourcepub unsafe fn initWithCoder(
this: Allocated<Self>,
a_decoder: &NSCoder,
) -> Option<Retained<Self>>
Available on crate feature MPSRayIntersector only.
pub unsafe fn initWithCoder( this: Allocated<Self>, a_decoder: &NSCoder, ) -> Option<Retained<Self>>
MPSRayIntersector only.Called by NSCoder to decode MPSKernels
This isn’t the right interface to decode a MPSKernel, but it is the one that NSCoder uses. To enable your NSCoder (e.g. NSKeyedUnarchiver) to set which device to use extend the object to adopt the MPSDeviceProvider protocol. Otherwise, the Metal system default device will be used.
§Safety
a_decoder possibly has further requirements.
Methods from Deref<Target = MPSAccelerationStructure>§
Sourcepub unsafe fn group(&self) -> Retained<MPSAccelerationStructureGroup>
👎DeprecatedAvailable on crate features MPSRayIntersector and MPSAccelerationStructureGroup only.
pub unsafe fn group(&self) -> Retained<MPSAccelerationStructureGroup>
MPSRayIntersector and MPSAccelerationStructureGroup only.The group this acceleration structure was created with
Sourcepub unsafe fn status(&self) -> MPSAccelerationStructureStatus
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn status(&self) -> MPSAccelerationStructureStatus
MPSRayIntersector only.Status indicating whether the acceleration structure has finished building
Sourcepub unsafe fn usage(&self) -> MPSAccelerationStructureUsage
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn usage(&self) -> MPSAccelerationStructureUsage
MPSRayIntersector only.Acceleration structure usage options. Changes to this property require rebuilding the acceleration structure. Defaults to MPSAccelerationStructureUsageNone.
Sourcepub unsafe fn setUsage(&self, usage: MPSAccelerationStructureUsage)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn setUsage(&self, usage: MPSAccelerationStructureUsage)
MPSRayIntersector only.Setter for usage.
Sourcepub unsafe fn rebuild(&self)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn rebuild(&self)
MPSRayIntersector only.Rebuild the acceleration structure
This method must be called before any intersection tests can be scheduled with this acceleration structure. Before calling this method, fill out the properties of the acceleration structure such as vertex buffer, instance buffer, etc. The acceleration structure should be rebuilt when its contents (e.g. vertices in a triangle acceleration structure) have been modified significantly and must be rebuilt when properties such as triangle count, vertex stride, etc. have changed. When the contents of the acceleration structure have only been modified slightly, it may be cheaper to refit the acceleration structure instead.
This method blocks until the acceleration structure has been rebuilt. Until the rebuild has completed, the acceleration structure cannot be copied, encoded with NSSecureCoding, rebuilt, or refit. Before this method can be called, any pending GPU writes to the vertex buffer, index buffer, etc. must be completed (and, for managed buffers, synchronized). Any prior intersection tests must also be completed before the acceleration structure can be rebuilt.
Sourcepub unsafe fn rebuildWithCompletionHandler(
&self,
completion_handler: MPSAccelerationStructureCompletionHandler,
)
👎DeprecatedAvailable on crate features MPSRayIntersector and block2 only.
pub unsafe fn rebuildWithCompletionHandler( &self, completion_handler: MPSAccelerationStructureCompletionHandler, )
MPSRayIntersector and block2 only.Rebuild the acceleration structure asynchronously
This method must be called before any intersection tests can be scheduled with this acceleration structure. Before calling this method, fill out the properties of the acceleration structure such as vertex buffer, instance buffer, etc. The acceleration structure should be rebuilt when its contents (e.g. vertices in a triangle acceleration structure) have been modified significantly and must be rebuilt when properties such as triangle count, vertex stride, etc. have changed. When the contents of the acceleration structure have only been modified slightly, it may be cheaper to refit the acceleration structure instead.
Until the rebuild has completed, the acceleration structure cannot be copied, encoded with NSSecureCoding, rebuilt, or refit. Before this method can be called, any pending GPU writes to the vertex buffer, index buffer, etc. must be completed (and, for managed buffers, synchronized). Any prior intersection tests must also be completed before the acceleration structure can be rebuilt.
§Safety
completion_handler must be a valid pointer.
Sourcepub unsafe fn encodeRefitToCommandBuffer(
&self,
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn encodeRefitToCommandBuffer( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, )
MPSRayIntersector only.Refit the existing acceleration structure to new data
This method is used to refit the acceleration structure to new vertex data, index data, instance data, etc. while preserving the existing acceleration structure topology. This is typically much faster than a full rebuild of the acceleration structure. Refitting can also be pipelined with other GPU work such as ray intersection.
Until the command buffer has completed, the acceleration structure cannot be copied, encoded with NSSecureCoding, or rebuilt. Changes to properties such as the triangle count or instance count might not be reflected. These changes require that the acceleration structure be rebuilt instead. The acceleration structure must be rebuilt at least once before this method can be called.
Sourcepub unsafe fn copyWithZone_device(
&self,
zone: *mut NSZone,
device: Option<&ProtocolObject<dyn MTLDevice>>,
) -> Retained<Self>
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn copyWithZone_device( &self, zone: *mut NSZone, device: Option<&ProtocolObject<dyn MTLDevice>>, ) -> Retained<Self>
MPSRayIntersector only.Create a a copy of this acceleration structure
The acceleration structure may be copied to a different Metal device. Buffer properties of the acceleration structure such as the vertex buffer, instance, buffer, etc. are set to nil. Copy these buffers to the new Metal device and assign them to the new acceleration structure instead. Do not copy the acceleration structure until any prior refit or rebuild operations have completed.
Parameter zone: This parameter is ignored. Memory zones are no longer used by Objective-C.
Parameter device: New Metal device
§Safety
zone must be a valid pointer or null.
Sourcepub unsafe fn copyWithZone_group(
&self,
zone: *mut NSZone,
group: &MPSAccelerationStructureGroup,
) -> Retained<Self>
👎DeprecatedAvailable on crate features MPSRayIntersector and MPSAccelerationStructureGroup only.
pub unsafe fn copyWithZone_group( &self, zone: *mut NSZone, group: &MPSAccelerationStructureGroup, ) -> Retained<Self>
MPSRayIntersector and MPSAccelerationStructureGroup only.Create a a copy of this acceleration structure
The acceleration structure may be copied with a different acceleration structure group. Buffer properties of the acceleration structure such as the vertex buffer, instance buffer, etc. are set to nil. Copy these buffers with the new Metal device and assign them to the new acceleration structure instead. Do not copy the acceleration structure until any prior refit or rebuild operations have completed.
Parameter zone: This parameter is ignored. Memory zones are no longer used by Objective-C.
Parameter group: New acceleration structure group
§Safety
zone must be a valid pointer or null.
Sourcepub unsafe fn encodeWithCoder(&self, coder: &NSCoder)
👎DeprecatedAvailable on crate feature MPSRayIntersector only.
pub unsafe fn encodeWithCoder(&self, coder: &NSCoder)
MPSRayIntersector only.Encode the acceleration structure with an NSCoder
Buffer properties such as the vertex buffer, index buffer, etc. are not be encoded. Encode and decode these buffers along with the acceleration structure instead. Do not encode the acceleration structure until any prior refit or rebuild operations have completed.
Parameter coder: An archiver object
§Safety
coder possibly has further requirements.
Methods from Deref<Target = MPSKernel>§
Sourcepub unsafe fn options(&self) -> MPSKernelOptions
Available on crate feature MPSCoreTypes only.
pub unsafe fn options(&self) -> MPSKernelOptions
MPSCoreTypes only.The set of options used to run the kernel. subsubsection_options
Sourcepub unsafe fn setOptions(&self, options: MPSKernelOptions)
Available on crate feature MPSCoreTypes only.
pub unsafe fn setOptions(&self, options: MPSKernelOptions)
MPSCoreTypes only.Setter for options.
Sourcepub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>
pub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>
The device on which the kernel will be used
Sourcepub unsafe fn label(&self) -> Option<Retained<NSString>>
pub unsafe fn label(&self) -> Option<Retained<NSString>>
A string to help identify this object.
Sourcepub unsafe fn copyWithZone_device(
&self,
zone: *mut NSZone,
device: Option<&ProtocolObject<dyn MTLDevice>>,
) -> Retained<Self>
pub unsafe fn copyWithZone_device( &self, zone: *mut NSZone, device: Option<&ProtocolObject<dyn MTLDevice>>, ) -> Retained<Self>
Make a copy of this MPSKernel for a new device
-copyWithZone: will call this API to make a copy of the MPSKernel on the same device. This interface may also be called directly to make a copy of the MPSKernel on a new device. Typically, the same MPSKernels should not be used to encode kernels on multiple command buffers from multiple threads. Many MPSKernels have mutable properties that might be changed by the other thread while this one is trying to encode. If you need to use a MPSKernel from multiple threads make a copy of it for each additional thread using -copyWithZone: or -copyWithZone:device:
Parameter zone: The NSZone in which to allocate the object
Parameter device: The device for the new MPSKernel. If nil, then use
self.device.
Returns: a pointer to a copy of this MPSKernel. This will fail, returning nil if the device is not supported. Devices must be MTLFeatureSet_iOS_GPUFamily2_v1 or later.
§Safety
zone must be a valid pointer or null.
Methods from Deref<Target = NSObject>§
Sourcepub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
Handle messages the object doesn’t recognize.
See Apple’s documentation for details.
Methods from Deref<Target = AnyObject>§
Sourcepub fn class(&self) -> &'static AnyClass
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());Sourcepub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
👎Deprecated: this is difficult to use correctly, use Ivar::load instead.
pub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
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.
Sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
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`
}
}Trait Implementations§
Source§impl AsRef<AnyObject> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl AsRef<AnyObject> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl AsRef<MPSAccelerationStructure> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl AsRef<MPSAccelerationStructure> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§fn as_ref(&self) -> &MPSAccelerationStructure
fn as_ref(&self) -> &MPSAccelerationStructure
Source§impl AsRef<MPSInstanceAccelerationStructure> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl AsRef<MPSInstanceAccelerationStructure> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl AsRef<MPSKernel> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl AsRef<MPSKernel> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl AsRef<NSObject> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl AsRef<NSObject> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl Borrow<AnyObject> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl Borrow<AnyObject> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl Borrow<MPSAccelerationStructure> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl Borrow<MPSAccelerationStructure> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§fn borrow(&self) -> &MPSAccelerationStructure
fn borrow(&self) -> &MPSAccelerationStructure
Source§impl Borrow<MPSKernel> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl Borrow<MPSKernel> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl Borrow<NSObject> for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl Borrow<NSObject> for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl ClassType for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl ClassType for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§const NAME: &'static str = "MPSInstanceAccelerationStructure"
const NAME: &'static str = "MPSInstanceAccelerationStructure"
Source§type Super = MPSAccelerationStructure
type Super = MPSAccelerationStructure
Source§type ThreadKind = <<MPSInstanceAccelerationStructure as ClassType>::Super as ClassType>::ThreadKind
type ThreadKind = <<MPSInstanceAccelerationStructure as ClassType>::Super as ClassType>::ThreadKind
Source§impl CopyingHelper for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl CopyingHelper for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§type Result = MPSInstanceAccelerationStructure
type Result = MPSInstanceAccelerationStructure
Self if the type has no
immutable counterpart. Read moreSource§impl Debug for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl Debug for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl Deref for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl Deref for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl Hash for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl Hash for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl Message for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl Message for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl NSCoding for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl NSCoding for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl NSCopying for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl NSCopying for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl NSObjectProtocol for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl NSObjectProtocol for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§fn isEqual(&self, other: Option<&AnyObject>) -> bool
fn isEqual(&self, other: Option<&AnyObject>) -> bool
Source§fn hash(&self) -> usize
fn hash(&self) -> usize
Source§fn isKindOfClass(&self, cls: &AnyClass) -> bool
fn isKindOfClass(&self, cls: &AnyClass) -> bool
Source§fn is_kind_of<T>(&self) -> bool
fn is_kind_of<T>(&self) -> bool
isKindOfClass directly, or cast your objects with AnyObject::downcast_refSource§fn isMemberOfClass(&self, cls: &AnyClass) -> bool
fn isMemberOfClass(&self, cls: &AnyClass) -> bool
Source§fn respondsToSelector(&self, aSelector: Sel) -> bool
fn respondsToSelector(&self, aSelector: Sel) -> bool
Source§fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
Source§fn debugDescription(&self) -> Retained<NSObject>
fn debugDescription(&self) -> Retained<NSObject>
Source§impl NSSecureCoding for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl NSSecureCoding for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl PartialEq for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl PartialEq for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§impl RefEncode for MPSInstanceAccelerationStructure
Available on crate feature MPSRayIntersector only.
impl RefEncode for MPSInstanceAccelerationStructure
MPSRayIntersector only.Source§const ENCODING_REF: Encoding = <MPSAccelerationStructure as ::objc2::RefEncode>::ENCODING_REF
const ENCODING_REF: Encoding = <MPSAccelerationStructure as ::objc2::RefEncode>::ENCODING_REF
impl DowncastTarget for MPSInstanceAccelerationStructure
MPSRayIntersector only.impl Eq for MPSInstanceAccelerationStructure
MPSRayIntersector only.