The renderer in its own OS process (priv/native/<system architecture>/cauldron_gpu_host),
so a crash in it leaves the VM running. The functions take the same arguments and
return the same values as CauldronGPU's; a caller switches by module.
{:ok, gpu} = CauldronGPU.Host.open(window: false, width: 640, height: 360)
cube = CauldronGPU.Host.mesh(gpu, CauldronGPU.Mesh.cube(1.0))
CauldronGPU.Host.submit(gpu, [{:instance, 1, %CauldronGPU.Instance{mesh: cube}}])A server process owns the renderer process and keeps the scene sent to it. When the
renderer process exits, the :events process receives
{:cauldron_gpu, window_id, :renderer_exited}; restart/1 starts a new one and sends
it the kept scene (meshes, textures, materials, instances, poses, lights, camera,
environment, effects). Changes submitted while the renderer is down are kept and
answered with {:error, "renderer exited"}. window_id stays the same across
restarts. Other events are those of CauldronGPU.
Handles are not freed by garbage collection. release/2 releases one; every handle a
process made is released when that process exits. A released object is freed once no
scene entry uses it. The server stops when the process that called open/1 exits.
Change batches of :shared_memory_threshold bytes or more (default 262144) reach the
renderer through a POSIX shared-memory object rather than the pipe.
Summary
Functions
The backends the renderer was built with, preferred first.
Makes a canvas and returns its handle, a texture's.
The next drawn frame; see CauldronGPU.capture/3.
Returns a specification to start this module under a supervisor.
Closes the window and stops the renderer process and its server.
How many frames the renderer process has drawn since it started.
Defines a material and returns its handle.
Uploads a mesh and returns its handle.
Starts a renderer process and opens a window or offscreen device in it. Options are
those of CauldronGPU.open/1, plus :shared_memory_threshold.
The renderer's OS process id, or nil while it is down.
Hides the pointer and reports only relative motion while enabled.
Releases a handle: the renderer frees its object once no scene entry uses it.
Removes the POSIX shared-memory object name, if there is one.
Changes an offscreen device's picture size (window: false).
Starts a new renderer process after the previous one exited and sends it the kept
scene. {:error, "running"} while the renderer is alive.
Sends one tick of changes (see CauldronGPU.Stream); a :tick is put before them.
The size of the terminal the VM runs in; see CauldronGPU.terminal_size/0.
Uploads a texture and returns its handle.
Types
@type t() :: %CauldronGPU.Host{ id: non_neg_integer(), info: CauldronGPU.info(), server: pid() }
Functions
@spec backends() :: [:metal | :vulkan]
The backends the renderer was built with, preferred first.
@spec canvas(t(), CauldronGPU.Canvas.t()) :: CauldronGPU.Handle.t()
Makes a canvas and returns its handle, a texture's.
@spec capture(t(), timeout(), keyword()) :: {:ok, %{width: pos_integer(), height: pos_integer(), shared_memory: String.t()}} | {:ok, %{width: pos_integer(), height: pos_integer(), pixels: binary()}} | {:error, term()}
The next drawn frame; see CauldronGPU.capture/3.
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec close(t()) :: :ok
Closes the window and stops the renderer process and its server.
@spec frames(t()) :: non_neg_integer()
How many frames the renderer process has drawn since it started.
@spec material(t(), CauldronGPU.Material.t()) :: CauldronGPU.Handle.t()
Defines a material and returns its handle.
@spec mesh(t(), CauldronGPU.Mesh.t()) :: CauldronGPU.Handle.t()
Uploads a mesh and returns its handle.
Starts a renderer process and opens a window or offscreen device in it. Options are
those of CauldronGPU.open/1, plus :shared_memory_threshold.
@spec os_pid(t()) :: non_neg_integer() | nil
The renderer's OS process id, or nil while it is down.
Hides the pointer and reports only relative motion while enabled.
@spec release(t(), CauldronGPU.Handle.t()) :: :ok
Releases a handle: the renderer frees its object once no scene entry uses it.
@spec resize(t(), pos_integer(), pos_integer()) :: :ok | {:error, String.t()}
Changes an offscreen device's picture size (window: false).
Starts a new renderer process after the previous one exited and sends it the kept
scene. {:error, "running"} while the renderer is alive.
@spec submit(t(), [CauldronGPU.Stream.change()]) :: :ok | {:error, String.t()}
Sends one tick of changes (see CauldronGPU.Stream); a :tick is put before them.
The size of the terminal the VM runs in; see CauldronGPU.terminal_size/0.
@spec texture(t(), CauldronGPU.Texture.t()) :: CauldronGPU.Handle.t()
Uploads a texture and returns its handle.