Package apple.metal.protocol

Interface MTLHeap

  • public interface MTLHeap
    [@protocol] MTLHeap

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      long cpuCacheMode()
      [@property] cpuCacheMode CPU cache mode for the heap.
      long currentAllocatedSize()
      [@property] currentAllocatedSize The size in bytes of the current heap allocation.
      MTLDevice device()
      [@property] device The device this heap was created against.
      long hazardTrackingMode()
      [@property] hazardTrackingMode Whether or not the heap is hazard tracked.
      java.lang.String label()
      [@property] label A string to help identify this heap.
      long maxAvailableSizeWithAlignment​(long alignment)
      maxAvailableSizeWithAlignment: The maximum size that can be successfully allocated from the heap in bytes, taking into notice given alignment.
      MTLBuffer newBufferWithLengthOptions​(long length, long options)
      newBufferWithLength:options: Create a new buffer backed by heap memory.
      MTLBuffer newBufferWithLengthOptionsOffset​(long length, long options, long offset)
      newBufferWithLength:options:offset: Create a new buffer backed by heap memory at the specified placement offset.
      MTLTexture newTextureWithDescriptor​(MTLTextureDescriptor desc)
      newTextureWithDescriptor: Create a new texture backed by heap memory.
      MTLTexture newTextureWithDescriptorOffset​(MTLTextureDescriptor descriptor, long offset)
      newTextureWithDescriptor:offset: Create a new texture backed by heap memory at the specified placement offset.
      long resourceOptions()
      [@property] resourceOptions A packed tuple of the storageMode, cpuCacheMode and hazardTrackingMode properties.
      void setLabel​(java.lang.String value)
      [@property] label A string to help identify this heap.
      long setPurgeableState​(long state)
      setPurgeabilityState: Set or query the purgeability state of the heap.
      long size()
      [@property] size Heap size in bytes, specified at creation time and rounded up to device specific alignment.
      long storageMode()
      [@property] storageMode Current heap storage mode, default is MTLStorageModePrivate.
      long type()
      [@property] type The type of the heap.
      long usedSize()
      [@property] usedSize The size in bytes, of all resources allocated from the heap.

    • 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

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

      • label

        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

        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

        MTLTexture newTextureWithDescriptor​(MTLTextureDescriptor desc)
        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​(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.

      • 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.

      • newBufferWithLengthOptionsOffset

        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

      • newTextureWithDescriptorOffset

        MTLTexture newTextureWithDescriptorOffset​(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.

      • resourceOptions

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

      • 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.