public class MPSInstanceAccelerationStructure extends MPSAccelerationStructure
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.
[@code] 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]; } [@endcode]
Next, create a buffer containing the acceleration structure index for each instance, and another acceleration structure containing the transformation matrix for each instance:
[@code] NSUInteger instanceBufferLength = sizeof(uint32_t) * instanceCount;
id
memcpy(instanceBuffer.contents, instances,
instanceBufferLength);
[instanceBuffer
didModifyRange:NSMakeRange(0, instanceBufferLength)];
instanceAccel.instanceBuffer = instanceBuffer;
// Similar for transformation matrix buffer
[@endcode]
Finally, rebuild the instance acceleration structure:
[@code]
[instanceAccel rebuild];
[@endcode]
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
MPSAccelerationStructure.Block_rebuildWithCompletionHandlerNSObject.Function_instanceMethodForSelector_ret, NSObject.Function_methodForSelector_ret| Modifier | Constructor and Description |
|---|---|
protected |
MPSInstanceAccelerationStructure(org.moe.natj.general.Pointer peer) |
| Modifier and Type | Method and Description |
|---|---|
boolean |
_supportsSecureCoding()
This property must return YES on all classes that allow secure coding.
|
NSArray<? extends MPSPolygonAccelerationStructure> |
accelerationStructures()
Acceleration structures available for use in this instance acceleration structure.
|
static boolean |
accessInstanceVariablesDirectly() |
static MPSInstanceAccelerationStructure |
alloc() |
static MPSInstanceAccelerationStructure |
allocWithZone(org.moe.natj.general.ptr.VoidPtr zone) |
static boolean |
automaticallyNotifiesObserversForKey(java.lang.String key) |
static void |
cancelPreviousPerformRequestsWithTarget(java.lang.Object aTarget) |
static void |
cancelPreviousPerformRequestsWithTargetSelectorObject(java.lang.Object aTarget,
org.moe.natj.objc.SEL aSelector,
java.lang.Object anArgument) |
static NSArray<java.lang.String> |
classFallbacksForKeyedArchiver() |
static org.moe.natj.objc.Class |
classForKeyedUnarchiver() |
static java.lang.String |
debugDescription_static() |
static java.lang.String |
description_static() |
static long |
hash_static() |
MPSInstanceAccelerationStructure |
init() |
MPSInstanceAccelerationStructure |
initWithCoder(NSCoder aDecoder)
NS_DESIGNATED_INITIALIZER
|
MPSInstanceAccelerationStructure |
initWithCoderDevice(NSCoder aDecoder,
java.lang.Object device)
Initialize the acceleration structure with an NSCoder and a Metal device.
|
MPSInstanceAccelerationStructure |
initWithCoderGroup(NSCoder aDecoder,
MPSAccelerationStructureGroup group)
Initialize the acceleration structure with an NSCoder and an acceleration structure
group, if the acceleration structure will be used in an instance hierarchy.
|
MPSInstanceAccelerationStructure |
initWithDevice(java.lang.Object device)
Initialize the acceleration structure with a Metal device
|
MPSInstanceAccelerationStructure |
initWithGroup(MPSAccelerationStructureGroup group)
Initialize the acceleration structure with an acceleration structure group, if the
acceleration structure will be used in an instance hierarchy.
|
MTLBuffer |
instanceBuffer()
Buffer containing the 32 bit unsigned integer index into the acceleration structure array
for each instance
|
long |
instanceBufferOffset()
Offset, in bytes, into the instance buffer.
|
long |
instanceCount()
Number of instances.
|
static NSObject.Function_instanceMethodForSelector_ret |
instanceMethodForSelector(org.moe.natj.objc.SEL aSelector) |
static NSMethodSignature |
instanceMethodSignatureForSelector(org.moe.natj.objc.SEL aSelector) |
static boolean |
instancesRespondToSelector(org.moe.natj.objc.SEL aSelector) |
static boolean |
isSubclassOfClass(org.moe.natj.objc.Class aClass) |
static NSSet<java.lang.String> |
keyPathsForValuesAffectingValueForKey(java.lang.String key) |
MTLBuffer |
maskBuffer()
Mask buffer containing one uint32_t mask per instance.
|
long |
maskBufferOffset()
Offset, in bytes, into the mask buffer.
|
static MPSInstanceAccelerationStructure |
new_objc() |
static boolean |
resolveClassMethod(org.moe.natj.objc.SEL sel) |
static boolean |
resolveInstanceMethod(org.moe.natj.objc.SEL sel) |
void |
setAccelerationStructures(NSArray<? extends MPSPolygonAccelerationStructure> value)
Acceleration structures available for use in this instance acceleration structure.
|
void |
setInstanceBuffer(MTLBuffer value)
Buffer containing the 32 bit unsigned integer index into the acceleration structure array
for each instance
|
void |
setInstanceBufferOffset(long value)
Offset, in bytes, into the instance buffer.
|
void |
setInstanceCount(long value)
Number of instances.
|
void |
setMaskBuffer(MTLBuffer value)
Mask buffer containing one uint32_t mask per instance.
|
void |
setMaskBufferOffset(long value)
Offset, in bytes, into the mask buffer.
|
void |
setTransformBuffer(MTLBuffer value)
Buffer containing one column major matrix_float4x4 transformation matrix per instance
|
void |
setTransformBufferOffset(long value)
Offset, in bytes, into the transform buffer.
|
void |
setTransformType(long value)
Instance transform type.
|
static void |
setVersion_static(long aVersion) |
static org.moe.natj.objc.Class |
superclass_static() |
static boolean |
supportsSecureCoding() |
MTLBuffer |
transformBuffer()
Buffer containing one column major matrix_float4x4 transformation matrix per instance
|
long |
transformBufferOffset()
Offset, in bytes, into the transform buffer.
|
long |
transformType()
Instance transform type.
|
static long |
version_static() |
copyWithZone, copyWithZoneDevice, copyWithZoneGroup, encodeRefitToCommandBuffer, encodeWithCoder, group, rebuild, rebuildWithCompletionHandler, setUsage, status, usagedevice, label, options, setLabel, setOptionsaccessibilityActivate, accessibilityActivationPoint, accessibilityAssistiveTechnologyFocusedIdentifiers, accessibilityAttributedHint, accessibilityAttributedLabel, accessibilityAttributedUserInputLabels, accessibilityAttributedValue, accessibilityContainerType, accessibilityCustomActions, accessibilityCustomRotors, accessibilityDecrement, accessibilityDragSourceDescriptors, accessibilityDropPointDescriptors, accessibilityElementAtIndex, accessibilityElementCount, accessibilityElementDidBecomeFocused, accessibilityElementDidLoseFocus, accessibilityElementIsFocused, accessibilityElements, accessibilityElementsHidden, accessibilityFrame, accessibilityHint, accessibilityIncrement, accessibilityLabel, accessibilityLanguage, accessibilityNavigationStyle, accessibilityPath, accessibilityPerformEscape, accessibilityPerformMagicTap, accessibilityRespondsToUserInteraction, accessibilityScroll, accessibilityTextualContext, accessibilityTraits, accessibilityUserInputLabels, accessibilityValue, accessibilityViewIsModal, addObserverForKeyPathOptionsContext, attemptRecoveryFromErrorOptionIndex, attemptRecoveryFromErrorOptionIndexDelegateDidRecoverSelectorContextInfo, autoContentAccessingProxy, awakeAfterUsingCoder, awakeFromNib, class_objc, classForCoder, classForKeyedArchiver, copy, dealloc, debugDescription, description, dictionaryWithValuesForKeys, didChangeValueForKey, didChangeValueForKeyWithSetMutationUsingObjects, didChangeValuesAtIndexesForKey, doesNotRecognizeSelector, fileManagerShouldProceedAfterError, fileManagerWillProcessPath, finalize_objc, forwardingTargetForSelector, forwardInvocation, hash, indexOfAccessibilityElement, isAccessibilityElement, isEqual, isKindOfClass, isMemberOfClass, isProxy, methodForSelector, methodSignatureForSelector, mutableArrayValueForKey, mutableArrayValueForKeyPath, mutableCopy, mutableOrderedSetValueForKey, mutableOrderedSetValueForKeyPath, mutableSetValueForKey, mutableSetValueForKeyPath, observationInfo, observeValueForKeyPathOfObjectChangeContext, performSelector, performSelectorInBackgroundWithObject, performSelectorOnMainThreadWithObjectWaitUntilDone, performSelectorOnMainThreadWithObjectWaitUntilDoneModes, performSelectorOnThreadWithObjectWaitUntilDone, performSelectorOnThreadWithObjectWaitUntilDoneModes, performSelectorWithObject, performSelectorWithObjectAfterDelay, performSelectorWithObjectAfterDelayInModes, performSelectorWithObjectWithObject, prepareForInterfaceBuilder, provideImageDataBytesPerRowOrigin_Size_UserInfo, removeObserverForKeyPath, removeObserverForKeyPathContext, replacementObjectForCoder, replacementObjectForKeyedArchiver, respondsToSelector, self, setAccessibilityActivationPoint, setAccessibilityAttributedHint, setAccessibilityAttributedLabel, setAccessibilityAttributedUserInputLabels, setAccessibilityAttributedValue, setAccessibilityContainerType, setAccessibilityCustomActions, setAccessibilityCustomRotors, setAccessibilityDragSourceDescriptors, setAccessibilityDropPointDescriptors, setAccessibilityElements, setAccessibilityElementsHidden, setAccessibilityFrame, setAccessibilityHint, setAccessibilityLabel, setAccessibilityLanguage, setAccessibilityNavigationStyle, setAccessibilityPath, setAccessibilityRespondsToUserInteraction, setAccessibilityTextualContext, setAccessibilityTraits, setAccessibilityUserInputLabels, setAccessibilityValue, setAccessibilityViewIsModal, setIsAccessibilityElement, setNilValueForKey, setObservationInfo, setShouldGroupAccessibilityChildren, setValueForKey, setValueForKeyPath, setValueForUndefinedKey, setValuesForKeysWithDictionary, shouldGroupAccessibilityChildren, superclass, validateValueForKeyError, validateValueForKeyPathError, valueForKey, valueForKeyPath, valueForUndefinedKey, willChangeValueForKey, willChangeValueForKeyWithSetMutationUsingObjects, willChangeValuesAtIndexesForKeyprotected MPSInstanceAccelerationStructure(org.moe.natj.general.Pointer peer)
public NSArray<? extends MPSPolygonAccelerationStructure> accelerationStructures()
public static boolean accessInstanceVariablesDirectly()
public static MPSInstanceAccelerationStructure alloc()
public static MPSInstanceAccelerationStructure allocWithZone(org.moe.natj.general.ptr.VoidPtr zone)
public static boolean automaticallyNotifiesObserversForKey(java.lang.String key)
public static void cancelPreviousPerformRequestsWithTarget(java.lang.Object aTarget)
public static void cancelPreviousPerformRequestsWithTargetSelectorObject(java.lang.Object aTarget,
org.moe.natj.objc.SEL aSelector,
java.lang.Object anArgument)
public static NSArray<java.lang.String> classFallbacksForKeyedArchiver()
public static org.moe.natj.objc.Class classForKeyedUnarchiver()
public static java.lang.String debugDescription_static()
public static java.lang.String description_static()
public static long hash_static()
public MPSInstanceAccelerationStructure init()
init in class MPSAccelerationStructurepublic MPSInstanceAccelerationStructure initWithCoder(NSCoder aDecoder)
NSCodinginitWithCoder in interface NSCodinginitWithCoder in class MPSAccelerationStructurepublic MPSInstanceAccelerationStructure initWithCoderDevice(NSCoder aDecoder, java.lang.Object device)
MPSAccelerationStructureinitWithCoderDevice in class MPSAccelerationStructureaDecoder - The NSCoder subclass with your serialized MPSKerneldevice - The MTLDevice on which to make the MPSKernelpublic MPSInstanceAccelerationStructure initWithCoderGroup(NSCoder aDecoder, MPSAccelerationStructureGroup group)
MPSAccelerationStructureinitWithCoderGroup in class MPSAccelerationStructurepublic MPSInstanceAccelerationStructure initWithDevice(java.lang.Object device)
MPSAccelerationStructureinitWithDevice in class MPSAccelerationStructuredevice - The device that the filter will be used on. May not be NULL.public MPSInstanceAccelerationStructure initWithGroup(MPSAccelerationStructureGroup group)
MPSAccelerationStructureThe Metal device is determined from the acceleration structure group. All acceleration structures in the instance hierarchy must share the same group.
initWithGroup in class MPSAccelerationStructurepublic MTLBuffer instanceBuffer()
public long instanceBufferOffset()
public long instanceCount()
public static NSObject.Function_instanceMethodForSelector_ret instanceMethodForSelector(org.moe.natj.objc.SEL aSelector)
public static NSMethodSignature instanceMethodSignatureForSelector(org.moe.natj.objc.SEL aSelector)
public static boolean instancesRespondToSelector(org.moe.natj.objc.SEL aSelector)
public static boolean isSubclassOfClass(org.moe.natj.objc.Class aClass)
public static NSSet<java.lang.String> keyPathsForValuesAffectingValueForKey(java.lang.String key)
public MTLBuffer maskBuffer()
public long maskBufferOffset()
public static MPSInstanceAccelerationStructure new_objc()
public static boolean resolveClassMethod(org.moe.natj.objc.SEL sel)
public static boolean resolveInstanceMethod(org.moe.natj.objc.SEL sel)
public void setAccelerationStructures(NSArray<? extends MPSPolygonAccelerationStructure> value)
public void setInstanceBuffer(MTLBuffer value)
public void setInstanceBufferOffset(long value)
public void setInstanceCount(long value)
public void setMaskBuffer(MTLBuffer value)
public void setMaskBufferOffset(long value)
public void setTransformBuffer(MTLBuffer value)
public void setTransformBufferOffset(long value)
public void setTransformType(long value)
public static void setVersion_static(long aVersion)
public static org.moe.natj.objc.Class superclass_static()
public static boolean supportsSecureCoding()
public boolean _supportsSecureCoding()
NSSecureCoding_supportsSecureCoding in interface NSSecureCoding_supportsSecureCoding in class MPSAccelerationStructurepublic MTLBuffer transformBuffer()
public long transformBufferOffset()
public long transformType()
public static long version_static()