Package apple.metalperformanceshaders

Class MPSInstanceAccelerationStructure

  • All Implemented Interfaces:
    NSCoding, NSCopying, NSSecureCoding, NSObject
    public class MPSInstanceAccelerationStructure
extends MPSAccelerationStructure
    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. [@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 instanceBuffer = [device newBufferWithLength:instanceBufferLength options:MTLResourceStorageModeManaged]; 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

    • Constructor Detail

      • MPSInstanceAccelerationStructure

        protected MPSInstanceAccelerationStructure​(org.moe.natj.general.Pointer peer)

    • Method Detail

      • accelerationStructures

        public NSArray<? extends MPSPolygonAccelerationStructure> accelerationStructures()
        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.

      • accessInstanceVariablesDirectly

        public static boolean accessInstanceVariablesDirectly()

      • allocWithZone

        public static java.lang.Object allocWithZone​(org.moe.natj.general.ptr.VoidPtr zone)

      • automaticallyNotifiesObserversForKey

        public static boolean automaticallyNotifiesObserversForKey​(java.lang.String key)

      • cancelPreviousPerformRequestsWithTarget

        public static void cancelPreviousPerformRequestsWithTarget​(java.lang.Object aTarget)

      • cancelPreviousPerformRequestsWithTargetSelectorObject

        public static void cancelPreviousPerformRequestsWithTargetSelectorObject​(java.lang.Object aTarget,
                                                                         org.moe.natj.objc.SEL aSelector,
                                                                         java.lang.Object anArgument)

      • classFallbacksForKeyedArchiver

        public static NSArray<java.lang.String> classFallbacksForKeyedArchiver()

      • classForKeyedUnarchiver

        public static org.moe.natj.objc.Class classForKeyedUnarchiver()

      • debugDescription_static

        public static java.lang.String debugDescription_static()

      • description_static

        public static java.lang.String description_static()

      • hash_static

        public static long hash_static()

      • initWithCoderDevice

        public MPSInstanceAccelerationStructure initWithCoderDevice​(NSCoder aDecoder,
                                                            java.lang.Object device)
        Description copied from class: MPSAccelerationStructure
        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.
        Overrides:
        initWithCoderDevice in class MPSAccelerationStructure
        Parameters:
        aDecoder - The NSCoder subclass with your serialized MPSKernel
        device - The MTLDevice on which to make the MPSKernel
        Returns:
        A new MPSKernel object, or nil if failure.

      • initWithDevice

        public MPSInstanceAccelerationStructure initWithDevice​(java.lang.Object device)
        Description copied from class: MPSAccelerationStructure
        Initialize the acceleration structure with a Metal device
        Overrides:
        initWithDevice in class MPSAccelerationStructure
        Parameters:
        device - The device that the filter will be used on. May not be NULL.
        Returns:
        a pointer to the newly initialized object. This will fail, returning nil if the device is not supported. Devices must be MTLFeatureSet_iOS_GPUFamily2_v1 or later.

      • instanceBuffer

        public MTLBuffer instanceBuffer()
        Buffer containing the 32 bit unsigned integer index into the acceleration structure array for each instance

      • instanceBufferOffset

        public long instanceBufferOffset()
        Offset, in bytes, into the instance buffer. Defaults to 0 bytes. Must be aligned to 4 bytes.

      • instanceCount

        public long instanceCount()
        Number of instances. Changes to this property require rebuilding the acceleration structure.

      • instanceMethodSignatureForSelector

        public static NSMethodSignature instanceMethodSignatureForSelector​(org.moe.natj.objc.SEL aSelector)

      • instancesRespondToSelector

        public static boolean instancesRespondToSelector​(org.moe.natj.objc.SEL aSelector)

      • isSubclassOfClass

        public static boolean isSubclassOfClass​(org.moe.natj.objc.Class aClass)

      • keyPathsForValuesAffectingValueForKey

        public static NSSet<java.lang.String> keyPathsForValuesAffectingValueForKey​(java.lang.String key)

      • maskBuffer

        public MTLBuffer maskBuffer()
        Mask buffer containing one uint32_t mask per instance. May be nil.

      • maskBufferOffset

        public long maskBufferOffset()
        Offset, in bytes, into the mask buffer. Defaults to 0 bytes. Must be aligned to 4 bytes.

      • new_objc

        public static java.lang.Object new_objc()

      • resolveClassMethod

        public static boolean resolveClassMethod​(org.moe.natj.objc.SEL sel)

      • resolveInstanceMethod

        public static boolean resolveInstanceMethod​(org.moe.natj.objc.SEL sel)

      • setAccelerationStructures

        public void setAccelerationStructures​(NSArray<? extends MPSPolygonAccelerationStructure> value)
        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.

      • setInstanceBuffer

        public void setInstanceBuffer​(MTLBuffer value)
        Buffer containing the 32 bit unsigned integer index into the acceleration structure array for each instance

      • setInstanceBufferOffset

        public void setInstanceBufferOffset​(long value)
        Offset, in bytes, into the instance buffer. Defaults to 0 bytes. Must be aligned to 4 bytes.

      • setInstanceCount

        public void setInstanceCount​(long value)
        Number of instances. Changes to this property require rebuilding the acceleration structure.

      • setMaskBuffer

        public void setMaskBuffer​(MTLBuffer value)
        Mask buffer containing one uint32_t mask per instance. May be nil.

      • setMaskBufferOffset

        public void setMaskBufferOffset​(long value)
        Offset, in bytes, into the mask buffer. Defaults to 0 bytes. Must be aligned to 4 bytes.

      • setTransformBuffer

        public void setTransformBuffer​(MTLBuffer value)
        Buffer containing one column major matrix_float4x4 transformation matrix per instance

      • setTransformBufferOffset

        public void setTransformBufferOffset​(long value)
        Offset, in bytes, into the transform buffer. Defaults to 0 bytes. Must be aligned to the stride of the transform type.

      • setTransformType

        public void setTransformType​(long value)
        Instance transform type. Defaults to MPSTransformTypeFloat4x4. Changes to this property require rebuilding the acceleration structure.

      • setVersion_static

        public static void setVersion_static​(long aVersion)

      • superclass_static

        public static org.moe.natj.objc.Class superclass_static()

      • supportsSecureCoding

        public static boolean supportsSecureCoding()

      • _supportsSecureCoding

        public boolean _supportsSecureCoding()
        Description copied from interface: NSSecureCoding
        This property must return YES on all classes that allow secure coding. Subclasses of classes that adopt NSSecureCoding and override initWithCoder: must also override this method and return YES. The Secure Coding Guide should be consulted when writing methods that decode data.
        Specified by:
        _supportsSecureCoding in interface NSSecureCoding
        Overrides:
        _supportsSecureCoding in class MPSAccelerationStructure

      • transformBuffer

        public MTLBuffer transformBuffer()
        Buffer containing one column major matrix_float4x4 transformation matrix per instance

      • transformBufferOffset

        public long transformBufferOffset()
        Offset, in bytes, into the transform buffer. Defaults to 0 bytes. Must be aligned to the stride of the transform type.

      • transformType

        public long transformType()
        Instance transform type. Defaults to MPSTransformTypeFloat4x4. Changes to this property require rebuilding the acceleration structure.

      • version_static

        public static long version_static()