Source code
Revision control
Copy as Markdown
Other Tools
//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
use objc2_foundation::*;
use crate::*;
/// Describes the mode of operation for an MTLHeap.
///
/// In this mode, resources are placed in the heap automatically.
/// Automatically placed resources have optimal GPU-specific layout, and may perform better than MTLHeapTypePlacement.
/// This heap type is recommended when the heap primarily contains temporary write-often resources.
///
/// In this mode, the app places resources in the heap.
/// Manually placed resources allow the app to control memory usage and heap fragmentation directly.
/// This heap type is recommended when the heap primarily contains persistent write-rarely resources.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtlheaptype?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MTLHeapType(pub NSInteger);
impl MTLHeapType {
#[doc(alias = "MTLHeapTypeAutomatic")]
pub const Automatic: Self = Self(0);
#[doc(alias = "MTLHeapTypePlacement")]
pub const Placement: Self = Self(1);
#[doc(alias = "MTLHeapTypeSparse")]
pub const Sparse: Self = Self(2);
}
unsafe impl Encode for MTLHeapType {
const ENCODING: Encoding = NSInteger::ENCODING;
}
unsafe impl RefEncode for MTLHeapType {
const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}
extern_class!(
/// [Apple's documentation](https://developer.apple.com/documentation/metal/mtlheapdescriptor?language=objc)
#[unsafe(super(NSObject))]
#[derive(Debug, PartialEq, Eq, Hash)]
pub struct MTLHeapDescriptor;
);
extern_conformance!(
unsafe impl NSCopying for MTLHeapDescriptor {}
);
unsafe impl CopyingHelper for MTLHeapDescriptor {
type Result = Self;
}
extern_conformance!(
unsafe impl NSObjectProtocol for MTLHeapDescriptor {}
);
impl MTLHeapDescriptor {
extern_methods!(
/// Requested size of the heap's backing memory.
///
/// The size may be rounded up to GPU page granularity.
#[unsafe(method(size))]
#[unsafe(method_family = none)]
pub fn size(&self) -> NSUInteger;
/// Setter for [`size`][Self::size].
#[unsafe(method(setSize:))]
#[unsafe(method_family = none)]
pub fn setSize(&self, size: NSUInteger);
#[cfg(feature = "MTLResource")]
/// Storage mode for the heap. Default is MTLStorageModePrivate.
///
/// All resources created from this heap share the same storage mode.
/// MTLStorageModeManaged and MTLStorageModeMemoryless are disallowed.
#[unsafe(method(storageMode))]
#[unsafe(method_family = none)]
pub fn storageMode(&self) -> MTLStorageMode;
#[cfg(feature = "MTLResource")]
/// Setter for [`storageMode`][Self::storageMode].
#[unsafe(method(setStorageMode:))]
#[unsafe(method_family = none)]
pub fn setStorageMode(&self, storage_mode: MTLStorageMode);
#[cfg(feature = "MTLResource")]
/// CPU cache mode for the heap. Default is MTLCPUCacheModeDefaultCache.
///
/// All resources created from this heap share the same cache mode.
/// CPU cache mode is ignored for MTLStorageModePrivate.
#[unsafe(method(cpuCacheMode))]
#[unsafe(method_family = none)]
pub fn cpuCacheMode(&self) -> MTLCPUCacheMode;
#[cfg(feature = "MTLResource")]
/// Setter for [`cpuCacheMode`][Self::cpuCacheMode].
#[unsafe(method(setCpuCacheMode:))]
#[unsafe(method_family = none)]
pub fn setCpuCacheMode(&self, cpu_cache_mode: MTLCPUCacheMode);
#[cfg(feature = "MTLResource")]
/// The sparse page size to use for resources created from the heap.
#[unsafe(method(sparsePageSize))]
#[unsafe(method_family = none)]
pub fn sparsePageSize(&self) -> MTLSparsePageSize;
#[cfg(feature = "MTLResource")]
/// Setter for [`sparsePageSize`][Self::sparsePageSize].
#[unsafe(method(setSparsePageSize:))]
#[unsafe(method_family = none)]
pub fn setSparsePageSize(&self, sparse_page_size: MTLSparsePageSize);
#[cfg(feature = "MTLResource")]
/// Set hazard tracking mode for the heap. The default value is MTLHazardTrackingModeDefault.
///
/// For heaps, MTLHazardTrackingModeDefault is treated as MTLHazardTrackingModeUntracked.
/// Setting hazardTrackingMode to MTLHazardTrackingModeTracked causes hazard tracking to be enabled heap.
/// When a resource on a hazard tracked heap is modified, reads and writes from all resources suballocated 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 all resources suballocated on that heap have completed.
/// For optimal performance, perform hazard tracking manually through MTLFence or MTLEvent instead.
/// All resources created from this heap shared the same hazard tracking mode.
#[unsafe(method(hazardTrackingMode))]
#[unsafe(method_family = none)]
pub fn hazardTrackingMode(&self) -> MTLHazardTrackingMode;
#[cfg(feature = "MTLResource")]
/// Setter for [`hazardTrackingMode`][Self::hazardTrackingMode].
#[unsafe(method(setHazardTrackingMode:))]
#[unsafe(method_family = none)]
pub fn setHazardTrackingMode(&self, hazard_tracking_mode: MTLHazardTrackingMode);
#[cfg(feature = "MTLResource")]
/// A packed tuple of the storageMode, cpuCacheMode and hazardTrackingMode properties.
///
/// Modifications to this property are reflected in the other properties and vice versa.
#[unsafe(method(resourceOptions))]
#[unsafe(method_family = none)]
pub fn resourceOptions(&self) -> MTLResourceOptions;
#[cfg(feature = "MTLResource")]
/// Setter for [`resourceOptions`][Self::resourceOptions].
#[unsafe(method(setResourceOptions:))]
#[unsafe(method_family = none)]
pub fn setResourceOptions(&self, resource_options: MTLResourceOptions);
/// The type of the heap. The default value is MTLHeapTypeAutomatic.
///
/// This constrains the resource creation functions that are available.
#[unsafe(method(type))]
#[unsafe(method_family = none)]
pub fn r#type(&self) -> MTLHeapType;
/// Setter for [`type`][Self::type].
#[unsafe(method(setType:))]
#[unsafe(method_family = none)]
pub fn setType(&self, r#type: MTLHeapType);
#[cfg(feature = "MTLResource")]
/// Specifies the largest sparse page size that the Metal heap supports.
///
/// This parameter only affects the heap if you set the ``type`` property of this descriptor
/// to ``MTLHeapType/MTLHeapTypePlacement``.
///
/// The value you assign to this property determines the compatibility of the Metal heap with with placement sparse
/// resources, because placement sparse resources require that their sparse page size be less than or equal to the
/// placement sparse page of the Metal heap that this property controls.
#[unsafe(method(maxCompatiblePlacementSparsePageSize))]
#[unsafe(method_family = none)]
pub fn maxCompatiblePlacementSparsePageSize(&self) -> MTLSparsePageSize;
#[cfg(feature = "MTLResource")]
/// Setter for [`maxCompatiblePlacementSparsePageSize`][Self::maxCompatiblePlacementSparsePageSize].
#[unsafe(method(setMaxCompatiblePlacementSparsePageSize:))]
#[unsafe(method_family = none)]
pub fn setMaxCompatiblePlacementSparsePageSize(
&self,
max_compatible_placement_sparse_page_size: MTLSparsePageSize,
);
);
}
/// Methods declared on superclass `NSObject`.
impl MTLHeapDescriptor {
extern_methods!(
#[unsafe(method(init))]
#[unsafe(method_family = init)]
pub fn init(this: Allocated<Self>) -> Retained<Self>;
#[unsafe(method(new))]
#[unsafe(method_family = new)]
pub fn new() -> Retained<Self>;
);
}
impl DefaultRetained for MTLHeapDescriptor {
#[inline]
fn default_retained() -> Retained<Self> {
Self::new()
}
}
extern_protocol!(
#[cfg(feature = "MTLAllocation")]
pub unsafe trait MTLHeap: MTLAllocation {
/// A string to help identify this heap.
#[unsafe(method(label))]
#[unsafe(method_family = none)]
fn label(&self) -> Option<Retained<NSString>>;
/// Setter for [`label`][Self::label].
///
/// This is [copied][objc2_foundation::NSCopying::copy] when set.
#[unsafe(method(setLabel:))]
#[unsafe(method_family = none)]
fn setLabel(&self, label: Option<&NSString>);
#[cfg(feature = "MTLDevice")]
/// The device this heap was created against. This heap can only be used with this device.
#[unsafe(method(device))]
#[unsafe(method_family = none)]
fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>;
#[cfg(feature = "MTLResource")]
/// Current heap storage mode, default is MTLStorageModePrivate.
///
/// All resources created from this heap share the same storage mode.
#[unsafe(method(storageMode))]
#[unsafe(method_family = none)]
fn storageMode(&self) -> MTLStorageMode;
#[cfg(feature = "MTLResource")]
/// CPU cache mode for the heap. Default is MTLCPUCacheModeDefaultCache.
///
/// All resources created from this heap share the same cache mode.
#[unsafe(method(cpuCacheMode))]
#[unsafe(method_family = none)]
fn cpuCacheMode(&self) -> MTLCPUCacheMode;
#[cfg(feature = "MTLResource")]
/// 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.
#[unsafe(method(hazardTrackingMode))]
#[unsafe(method_family = none)]
fn hazardTrackingMode(&self) -> MTLHazardTrackingMode;
#[cfg(feature = "MTLResource")]
/// A packed tuple of the storageMode, cpuCacheMode and hazardTrackingMode properties.
#[unsafe(method(resourceOptions))]
#[unsafe(method_family = none)]
fn resourceOptions(&self) -> MTLResourceOptions;
/// Heap size in bytes, specified at creation time and rounded up to device specific alignment.
#[unsafe(method(size))]
#[unsafe(method_family = none)]
fn size(&self) -> NSUInteger;
/// The size in bytes, of all resources allocated from the heap.
#[unsafe(method(usedSize))]
#[unsafe(method_family = none)]
fn usedSize(&self) -> NSUInteger;
/// The size in bytes of the current heap allocation.
#[unsafe(method(currentAllocatedSize))]
#[unsafe(method_family = none)]
fn currentAllocatedSize(&self) -> NSUInteger;
/// 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.
#[unsafe(method(maxAvailableSizeWithAlignment:))]
#[unsafe(method_family = none)]
fn maxAvailableSizeWithAlignment(&self, alignment: NSUInteger) -> NSUInteger;
#[cfg(all(feature = "MTLBuffer", feature = "MTLResource"))]
/// 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.
#[unsafe(method(newBufferWithLength:options:))]
#[unsafe(method_family = new)]
fn newBufferWithLength_options(
&self,
length: NSUInteger,
options: MTLResourceOptions,
) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>;
#[cfg(all(feature = "MTLResource", feature = "MTLTexture"))]
/// 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.
#[unsafe(method(newTextureWithDescriptor:))]
#[unsafe(method_family = new)]
fn newTextureWithDescriptor(
&self,
descriptor: &MTLTextureDescriptor,
) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
#[cfg(feature = "MTLResource")]
/// Set or query the purgeability state of the heap.
#[unsafe(method(setPurgeableState:))]
#[unsafe(method_family = none)]
fn setPurgeableState(&self, state: MTLPurgeableState) -> MTLPurgeableState;
/// The type of the heap. The default value is MTLHeapTypeAutomatic.
///
/// This constrains the resource creation functions that are available on the heap.
#[unsafe(method(type))]
#[unsafe(method_family = none)]
fn r#type(&self) -> MTLHeapType;
#[cfg(all(feature = "MTLBuffer", feature = "MTLResource"))]
/// 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.
///
/// Parameter `length`: The requested size of the buffer, in bytes.
///
/// Parameter `options`: The requested options of the buffer, of which the storage and CPU cache mode must match these of the heap.
///
/// Parameter `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
///
/// # Safety
///
/// `offset` might not be bounds-checked.
#[unsafe(method(newBufferWithLength:options:offset:))]
#[unsafe(method_family = new)]
unsafe fn newBufferWithLength_options_offset(
&self,
length: NSUInteger,
options: MTLResourceOptions,
offset: NSUInteger,
) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>;
#[cfg(all(feature = "MTLResource", feature = "MTLTexture"))]
/// 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.
///
/// Parameter `descriptor`: The requested properties of the texture, of which the storage and CPU cache mode must match those of the heap.
///
/// Parameter `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.
///
/// # Safety
///
/// `offset` might not be bounds-checked.
#[unsafe(method(newTextureWithDescriptor:offset:))]
#[unsafe(method_family = new)]
unsafe fn newTextureWithDescriptor_offset(
&self,
descriptor: &MTLTextureDescriptor,
offset: NSUInteger,
) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
#[cfg(all(feature = "MTLAccelerationStructure", feature = "MTLResource"))]
/// 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.
///
/// # Safety
///
/// `size` might not be bounds-checked.
#[unsafe(method(newAccelerationStructureWithSize:))]
#[unsafe(method_family = new)]
unsafe fn newAccelerationStructureWithSize(
&self,
size: NSUInteger,
) -> Option<Retained<ProtocolObject<dyn MTLAccelerationStructure>>>;
#[cfg(all(feature = "MTLAccelerationStructure", feature = "MTLResource"))]
/// 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.
#[unsafe(method(newAccelerationStructureWithDescriptor:))]
#[unsafe(method_family = new)]
fn newAccelerationStructureWithDescriptor(
&self,
descriptor: &MTLAccelerationStructureDescriptor,
) -> Option<Retained<ProtocolObject<dyn MTLAccelerationStructure>>>;
#[cfg(all(feature = "MTLAccelerationStructure", feature = "MTLResource"))]
/// 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.
///
/// Parameter `size`: The requested size of the acceleration structure, in bytes.
///
/// Parameter `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
///
/// # Safety
///
/// - `size` might not be bounds-checked.
/// - `offset` might not be bounds-checked.
#[unsafe(method(newAccelerationStructureWithSize:offset:))]
#[unsafe(method_family = new)]
unsafe fn newAccelerationStructureWithSize_offset(
&self,
size: NSUInteger,
offset: NSUInteger,
) -> Option<Retained<ProtocolObject<dyn MTLAccelerationStructure>>>;
#[cfg(all(feature = "MTLAccelerationStructure", feature = "MTLResource"))]
/// 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.
///
/// Parameter `descriptor`: The acceleration structure descriptor
///
/// Parameter `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
///
/// # Safety
///
/// `offset` might not be bounds-checked.
#[unsafe(method(newAccelerationStructureWithDescriptor:offset:))]
#[unsafe(method_family = new)]
unsafe fn newAccelerationStructureWithDescriptor_offset(
&self,
descriptor: &MTLAccelerationStructureDescriptor,
offset: NSUInteger,
) -> Option<Retained<ProtocolObject<dyn MTLAccelerationStructure>>>;
}
);