Reference/Graphics & compute

Graphics & compute

CGLRun

Load and dispatch a compiled Metal kernel using ordinary Catalyst buffers and values.

C++23 mc/CGL.h macOS · Metal
#include <mc/CGL.h>

Link Catalyst::MacShared or Catalyst::MacStatic and provide a compatible GPU. The constructor takes a .metallib path and kernel function name.

Cosmic gpu functions and kernel entry points can be compiled with mc-cosmic --metallib. Add arguments in kernel order, configure the grid and thread group, then dispatch.

Jump to a declaration · 16
CGLRun CGLRun::add CGLRun::await CGLRun::CGLRun CGLRun::clear CGLRun::maxThreads CGLRun::operator<< CGLRun::operator= CGLRun::outputLog CGLRun::run CGLRun::setGrid CGLRun::setLog CGLRun::setMemory CGLRun::setThreadGroup CGLRun::start CGLRun::~CGLRun

CGLRun

class CGLRun

Methods

CGLRun

CGLRun(const cstr& file, const cstr& func);
CGLRun(const CGLRun&) = delete;

Loads the specified compiled Metal library and selects its named kernel. The library and function must exist and be compatible with the available GPU.

operator<<

template<class T> CGLRun& operator<<(T&& x);

Registers the next argument through add() and returns the runner for chaining. Arguments are bound in insertion order.

add

template<class T> void add(CVector<T>& v);
template<class T> void add(T& x);
void add(void* data, size_t bytes);

Registers an argument in kernel order. Keep supplied memory allocated at the same address until dispatch finishes.

clear

void clear();

Clears the registered argument list.

maxThreads

size_t maxThreads() const;

Returns the maximum thread count allowed in a threadgroup for this kernel. The product of dimensions supplied to setThreadGroup() must not exceed it.

setGrid

void setGrid(size_t gx, size_t gy = 1, size_t gz = 1);

Sets the dispatched thread grid dimensions.

setThreadGroup

void setThreadGroup(size_t tx, size_t ty = 1, size_t tz = 1);

Sets the threadgroup dimensions; the product must fit the kernel/device limit.

setMemory

void setMemory(size_t scratchBytesPerThread);

Sets scratch bytes per dispatched thread.

setLog

void setLog(size_t logBytesPerThread);

Sets log bytes per dispatched thread.

start

void start();

Copies bound inputs and submits work asynchronously. Keep host storage stable until await() copies the results back.

await

void await();

Waits for submitted work and makes output available in the bound host buffers.

run

void run();

Submits and waits for completion.

outputLog

void outputLog(size_t thread);

Outputs the selected dispatched thread’s kernel log. Configure log bytes before dispatch and wait for completion before reading logs.