VkFFT Documentation

Methods that do not begin with alloc, new, copy, or mutableCopy typically add the created object to an AutoreleasePool. These objects are released when the pool is drained.

• Main Thread: The pool is typically drained when the thread returns control to the RunLoop (e.g., at the end of a frame).
• Additional Threads: You must create and manage an AutoreleasePool for any additional threads you create to prevent memory leaks.
• Extending Lifetime: If you need an autoreleased object to live longer than the current pool's scope, call retain() on it before the pool is drained. You then become responsible for calling release() later.

Debugging Leaks

• Environment Variable: Set OBJC_DEBUG_MISSING_POOLS=YES to print a runtime warning when an autoreleased object is leaked due to a missing enclosing AutoreleasePool on its thread.
• macOS Tooling: Use leaks --autoreleasePools <process_id> to view a listing of your program's AutoreleasePools and their contents.

metal-cpp follows Cocoa/Cocoa Touch object allocation policies. Because C++ objects are not eligible for Automatic Reference Counting (ARC), you must manually manage lifecycles using reference counting:

1. Ownership via alloc, new, copy, or mutableCopy: You own any object returned by methods starting with these prefixes. The retainCount is 1.
2. Taking ownership: Use the retain() method to take ownership of an existing object or to prevent it from being deallocated by other operations.
3. Relinquishing ownership: When you no longer need an object you own, you must call release() or autorelease().
4. Do not relinquish what you do not own: Only call release/autorelease on objects you have explicitly retained or obtained via alloc/new/copy.

Note: When retainCount reaches 0, the object is immediately deallocated. Calling methods on a deallocated object will cause a crash.

VkFFT is a header-only library that requires specific backend definitions and dependencies depending on the target API. You must provide the correct VKFFT_BACKEND definition during compilation.

Vulkan

• Requirements: vkFFT.h and glslang compiler.
• Backend Definition: VKFFT_BACKEND=0.
• Note: Vulkan 1.0 is required for single/double precision; Vulkan 1.1 is required for half precision.

CUDA/HIP

• Requirements: vkFFT.h and a system with NVRTC (for CUDA) or HIPRTC (for HIP) built.
• Backend Definitions:
  • CUDA: VKFFT_BACKEND=1
  • HIP: VKFFT_BACKEND=2

OpenCL

• Requirements: vkFFT.h.
• Backend Definition: VKFFT_BACKEND=3

Level Zero

• Requirements: vkFFT.h, Clang, and llvm-spirv must be valid system calls.
• Backend Definition: VKFFT_BACKEND=4

Metal

• Requirements: vkFFT.h and metal-cpp (for C++ bindings to Apple's Foundation, QuartzCore, and Metal libraries).
• Backend Definition: VKFFT_BACKEND=5

You can bridge between metal-cpp objects and CoreFoundation or Objective-C types using C++ casts.

CoreFoundation Example:

MTL::AccelerationStructureTriangleGeometryDescriptor* pGeoDescriptor  = MTL::AccelerationStructureTriangleGeometryDescriptor::alloc()->init();
CFTypeRef                                             descriptors[]   = { ( CFTypeRef )( pGeoDescriptor ) };
NS::Array*                                            pGeoDescriptors = ( NS::Array* )( CFArrayCreate( kCFAllocatorDefault, descriptors, SIZEOF_ARRAY( descriptors), &kCFTypeArrayCallBacks ) );

// ...

pGeoDescriptors->release();

QuartzCore (CAMetalLayer) Example: When working with Objective-C layers, use a bridge cast to access the CA::MetalDrawable.

CAMetalLayer*         metalLayer         = /* get your layer from your view */;
id< CAMetalDrawable > metalDrawable      = [metalLayer nextDrawable];
CA::MetalDrawable*    pMetalCppDrawable  = ( __bridge CA::MetalDrawable* ) metalDrawable;

Metal function calls map directly to the MTL:: namespace. For example, creating a sampler involves allocating a descriptor, configuring it, and then creating the sampler state from the device.

MTL::SamplerDescriptor* pSamplerDescriptor = MTL::SamplerDescriptor::alloc()->init();

pSamplerDescriptor->setSAddressMode( MTL::SamplerAddressModeRepeat );
pSamplerDescriptor->setTAddressMode( MTL::SamplerAddressModeRepeat );
pSamplerDescriptor->setRAddressMode( MTL::SamplerAddressModeRepeat );
pSamplerDescriptor->setMagFilter( MTL::SamplerMinMagFilterLinear );
pSamplerDescriptor->setMinFilter( MTL::SamplerMinMagFilterLinear );
pSamplerDescriptor->setMipFilter( MTL::SamplerMipFilterLinear );
pSamplerDescriptor->setSupportArgumentBuffers( true );

MTL::SamplerState* pSamplerState = pDevice->newSamplerState( pSamplerDescriptor );

pSamplerDescriptor->release();

// ...

pSamplerState->release();