Package apple.metal.protocol

Interface MTLHeap

  • public interface MTLHeap
    [@protocol] MTLHeap API-Since: 10.0

    • Method Detail

      • cpuCacheMode

        long cpuCacheMode()
        [@property] cpuCacheMode CPU cache mode for the heap. Default is MTLCPUCacheModeDefaultCache. All resources created from this heap share the same cache mode.

      • device

        @NotNull
@NotNull MTLDevice device()
        [@property] device The device this heap was created against. This heap can only be used with this device.

      • label

        @Nullable
@Nullable java.lang.String label()
        [@property] label A string to help identify this heap.

      • maxAvailableSizeWithAlignment

        long maxAvailableSizeWithAlignment​(long alignment)
        maxAvailableSizeWithAlignment: The maximum size that can be successfully allocated from the heap in bytes, taking into notice given alignment. Alignment needs to be zero, or power of two. Provides a measure of fragmentation within the heap.

      • newBufferWithLengthOptions

        @Nullable
@Nullable MTLBuffer newBufferWithLengthOptions​(long length,
                                               long options)
        newBufferWithLength:options: Create a new buffer backed by heap memory. The requested storage and CPU cache modes must match the storage and CPU cache modes of the heap.
        Returns:
        The buffer or nil if heap is full.

      • newTextureWithDescriptor

        @Nullable
@Nullable MTLTexture newTextureWithDescriptor​(@NotNull
                                              @NotNull MTLTextureDescriptor descriptor)
        newTextureWithDescriptor: Create a new texture backed by heap memory. The requested storage and CPU cache modes must match the storage and CPU cache modes of the heap, with the exception that the requested storage mode can be MTLStorageModeMemoryless.
        Returns:
        The texture or nil if heap is full.

      • setLabel

        void setLabel​(@Nullable
              @Nullable java.lang.String value)
        [@property] label A string to help identify this heap.

      • setPurgeableState

        long setPurgeableState​(long state)
        setPurgeabilityState: Set or query the purgeability state of the heap.

      • size

        long size()
        [@property] size Heap size in bytes, specified at creation time and rounded up to device specific alignment.

      • storageMode

        long storageMode()
        [@property] storageMode Current heap storage mode, default is MTLStorageModePrivate. All resources created from this heap share the same storage mode.

      • usedSize

        long usedSize()
        [@property] usedSize The size in bytes, of all resources allocated from the heap.

      • currentAllocatedSize

        long currentAllocatedSize()
        [@property] currentAllocatedSize The size in bytes of the current heap allocation. API-Since: 11.0

      • hazardTrackingMode

        long hazardTrackingMode()
        [@property] hazardTrackingMode Whether or not the heap is hazard tracked. When a resource on a hazard tracked heap is modified, reads and writes from any other resource on that heap will be delayed until the modification is complete. Similarly, modifying heap resources will be delayed until all in-flight reads and writes from resources suballocated on that heap have completed. For optimal performance, perform hazard tracking manually through MTLFence or MTLEvent instead. Resources on the heap may opt-out of hazard tracking individually when the heap is hazard tracked, however resources cannot opt-in to hazard tracking when the heap is not hazard tracked. API-Since: 13.0

      • newBufferWithLengthOptionsOffset

        @Nullable
@Nullable MTLBuffer newBufferWithLengthOptionsOffset​(long length,
                                                     long options,
                                                     long offset)
        newBufferWithLength:options:offset: Create a new buffer backed by heap memory at the specified placement offset. This method can only be used when heapType is set to MTLHeapTypePlacement. Use "MTLDevice heapBufferSizeAndAlignWithLength:options:" to determine requiredSize and requiredAlignment. Any resources that exist in this heap at overlapping half-open range [offset, offset + requiredSize) are implicitly aliased with the new resource.
        Parameters:
        length - The requested size of the buffer, in bytes.
        options - The requested options of the buffer, of which the storage and CPU cache mode must match these of the heap.
        offset - The requested offset of the buffer inside the heap, in bytes. Behavior is undefined if "offset + requiredSize > heap.size" or "offset % requiredAlignment != 0".
        Returns:
        The buffer, or nil if the heap is not a placement heap API-Since: 13.0

      • newTextureWithDescriptorOffset

        @Nullable
@Nullable MTLTexture newTextureWithDescriptorOffset​(@NotNull
                                                    @NotNull MTLTextureDescriptor descriptor,
                                                    long offset)
        newTextureWithDescriptor:offset: Create a new texture backed by heap memory at the specified placement offset. This method can only be used when heapType is set to MTLHeapTypePlacement. Use "MTLDevice heapTextureSizeAndAlignWithDescriptor:" to determine requiredSize and requiredAlignment. Any resources that exist in this heap at overlapping half-open range [offset, offset + requiredSize) are implicitly aliased with the new resource.
        Parameters:
        descriptor - The requested properties of the texture, of which the storage and CPU cache mode must match those of the heap.
        offset - The requested offset of the texture inside the heap, in bytes. Behavior is undefined if "offset + requiredSize > heap.size" and "offset % requiredAlignment != 0".
        Returns:
        The texture, or nil if the heap is not a placement heap. API-Since: 13.0

      • resourceOptions

        long resourceOptions()
        [@property] resourceOptions A packed tuple of the storageMode, cpuCacheMode and hazardTrackingMode properties. API-Since: 13.0

      • type

        long type()
        [@property] type The type of the heap. The default value is MTLHeapTypeAutomatic. This constrains the resource creation functions that are available on the heap. API-Since: 13.0

      • newAccelerationStructureWithDescriptor

        @Nullable
@Nullable MTLAccelerationStructure newAccelerationStructureWithDescriptor​(@NotNull
                                                                          @NotNull MTLAccelerationStructureDescriptor descriptor)
        newAccelerationStructureWithDescriptor: Create a new acceleration structure backed by heap memory. This is a convenience method which creates the acceleration structure backed by heap memory. The acceleration structure size is inferred based on the descriptor.
        Returns:
        The acceleration structure or nil if heap is full. Note that the MTLAccelerationStructure merely represents storage for an acceleration structure. It will still need to be populated via a build, copy, refit, etc. API-Since: 16.0

      • newAccelerationStructureWithDescriptorOffset

        @Nullable
@Nullable MTLAccelerationStructure newAccelerationStructureWithDescriptorOffset​(@NotNull
                                                                                @NotNull MTLAccelerationStructureDescriptor descriptor,
                                                                                long offset)
        newAccelerationStructureWithDescriptor:offset: Create a new acceleration structure backed by heap memory at the specified placement offset. This is a convenience method which computes the acceleration structure size based on the descriptor. This method can only be used when heapType is set to MTLHeapTypePlacement. Use "MTLDevice heapAccelerationStructureSizeAndAlignWithSize:" or "MTLDevice heapAccelerationStructureSizeAndAlignWithDescriptor:" to determine requiredSize and requiredAlignment. Any resources that exist in this heap at overlapping half-open range [offset, offset + requiredSize) are implicitly aliased with the new resource.
        Parameters:
        descriptor - The acceleration structure descriptor
        offset - The requested offset of the acceleration structure inside the heap, in bytes. Behavior is undefined if "offset + requiredSize > heap.size" or "offset % requiredAlignment != 0".
        Returns:
        The acceleration structure, or nil if the heap is not a placement heap API-Since: 16.0

      • newAccelerationStructureWithSize

        @Nullable
@Nullable MTLAccelerationStructure newAccelerationStructureWithSize​(long size)
        newAccelerationStructureWithSize: Create a new acceleration structure backed by heap memory.
        Returns:
        The acceleration structure or nil if heap is full. Note that the MTLAccelerationStructure merely represents storage for an acceleration structure. It will still need to be populated via a build, copy, refit, etc. API-Since: 16.0

      • newAccelerationStructureWithSizeOffset

        @Nullable
@Nullable MTLAccelerationStructure newAccelerationStructureWithSizeOffset​(long size,
                                                                          long offset)
        newAccelerationStructureWithSize:offset: Create a new acceleration structure backed by heap memory at the specified placement offset. This method can only be used when heapType is set to MTLHeapTypePlacement. Use "MTLDevice heapAccelerationStructureSizeAndAlignWithSize:" or "MTLDevice heapAccelerationStructureSizeAndAlignWithDescriptor:" to determine requiredSize and requiredAlignment. Any resources that exist in this heap at overlapping half-open range [offset, offset + requiredSize) are implicitly aliased with the new resource.
        Parameters:
        size - The requested size of the acceleration structure, in bytes.
        offset - The requested offset of the acceleration structure inside the heap, in bytes. Behavior is undefined if "offset + requiredSize > heap.size" or "offset % requiredAlignment != 0".
        Returns:
        The acceleration structure, or nil if the heap is not a placement heap API-Since: 16.0