GeodeNativeRoot.h File Reference

Native Geode root selection. More...

#include <cstdint>
#include <memory>
#include <optional>
#include <ostream>
#include <span>
#include <string_view>
#include "donner/base/Utils.h"
#include "donner/gpu/Device.h"

Include dependency graph for GeodeNativeRoot.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	donner::geode::GeodeGpuRootCapabilities
	Capabilities shared by runtime devices opened over one browser GPU device. More...
class	donner::geode::GeodeGpuRoot
	Owns the browser GPU device and loss condition shared by logical Geode contexts. More...
struct	donner::geode::GpuRootSelection
	Inputs to browser-root selection. A named unsupported backend is refused. More...
struct	donner::geode::GeodeRuntimeDevice
	One logical runtime device over the selected browser root. More...

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.

Enumerations
enum class	donner::geode::GpuBackendKind : uint8_t {   NativeMetal ,   NativeVulkan ,   Browser ,   NativeMetal ,   NativeVulkan ,   Browser ,   External }
	The backend selected for a Geode runtime device. More...

Functions
std::string_view	donner::geode::GpuBackendKindName (GpuBackendKind kind)
	Human-readable name of a selected backend.
std::ostream &	donner::geode::operator<< (std::ostream &os, GpuBackendKind kind)
	Prints the kind's human-readable name.
gpu::Result< GpuBackendKind >	donner::geode::ProcessDefaultGpuBackendKind ()
	In WebAssembly builds, the backend DONNER_GPU_BACKEND requests, or the browser backend when it is unset or empty.
gpu::Result< GpuBackendKind >	donner::geode::ResolveGpuBackendKind (const GpuRootSelection &options, std::string_view request)
	The backend SelectGpuRoot opens for options, without opening it.
std::shared_ptr< GeodeGpuRoot >	donner::geode::SelectGpuRoot (const GpuRootSelection &options)
	In WebAssembly builds, opens the browser's GPU device as a root. When the caller names no backend, halts if DONNER_GPU_BACKEND is invalid or names a native backend. A caller-named native backend halts when DONNER_GPU_BACKEND is non-empty and returns null otherwise. Also returns null when the device request fails.
std::shared_ptr< GeodeGpuRoot >	donner::geode::AdoptNativeVulkanRoot (std::shared_ptr< gpu::vulkan::VulkanSharedRoot > nativeRoot, std::shared_ptr< gpu::DeviceLostState > lostState)
	Adopts a completed native Vulkan root, for example one an embedder selected for its actual presentation surface.
GeodeRuntimeDevice	donner::geode::CreateGpuDeviceOver (std::shared_ptr< GeodeGpuRoot > root)
	In WebAssembly builds, opens one runtime device over the browser root, sharing its loss condition.

Detailed Description

Native Geode root selection.

Enumeration Type Documentation

GpuBackendKind

enum class donner::geode::GpuBackendKind : uint8_t

strong

The backend selected for a Geode runtime device.

Enumerator
External	Runtime devices a GeodeRuntimeDeviceSource opens. Never selected: only adopting a source produces it.

Function Documentation

AdoptNativeVulkanRoot()

std::shared_ptr< GeodeGpuRoot > donner::geode::AdoptNativeVulkanRoot	(	std::shared_ptr< gpu::vulkan::VulkanSharedRoot >	nativeRoot,
		std::shared_ptr< gpu::DeviceLostState >	lostState )

Adopts a completed native Vulkan root, for example one an embedder selected for its actual presentation surface.

Parameters

nativeRoot	Completed Vulkan instance, physical and logical device, and queue.
lostState	Loss condition nativeRoot was opened with.

Returns

The root, or null when either input is null, lostState is not the condition nativeRoot shares, or this platform has no native Vulkan backend.

CreateGpuDeviceOver()

GeodeRuntimeDevice donner::geode::CreateGpuDeviceOver

(

std::shared_ptr< GeodeGpuRoot >

root

)

In WebAssembly builds, opens one runtime device over the browser root, sharing its loss condition.

Opens one runtime device over root.

Every logical rendering context gets its own, with its own handle tables and submission serials, while all of them share the root's loss condition.

Parameters

root	Root to render through; must not be null.

Returns

The device, or an empty device when the backend could not open one.

GpuBackendKindName()

std::string_view donner::geode::GpuBackendKindName

(

GpuBackendKind

kind

)

Human-readable name of a selected backend.

Parameters

kind	Backend kind to name.

operator<<()

std::ostream & donner::geode::operator<<	(	std::ostream &	os,
		GpuBackendKind	kind )

Prints the kind's human-readable name.

Parameters

os	Output stream.
kind	Value to output.

ProcessDefaultGpuBackendKind()

gpu::Result< GpuBackendKind > donner::geode::ProcessDefaultGpuBackendKind

(

)

In WebAssembly builds, the backend DONNER_GPU_BACKEND requests, or the browser backend when it is unset or empty.

The backend DONNER_GPU_BACKEND requests: metal or vulkan in any letter case, or the platform default (native Metal on Apple, native Vulkan on Linux) when the variable is unset or empty.

Returns

The kind, or an error when the variable names no backend or the platform has no native backend.

ResolveGpuBackendKind()

gpu::Result< GpuBackendKind > donner::geode::ResolveGpuBackendKind	(	const GpuRootSelection &	options,
		std::string_view	request )

The backend SelectGpuRoot opens for options, without opening it.

The first of these that applies decides: the backend the caller names, the one request names, and the platform default.

Parameters

options	Caller-supplied inputs.
request	Value of DONNER_GPU_BACKEND; empty when it is unset or empty.

Returns

The kind, or an error when the caller names no backend and a non-empty request names none, the external kind is named, no backend applies on this platform, or the Vulkan presentation options are inconsistent with each other or with the resolved backend.

SelectGpuRoot()

std::shared_ptr< GeodeGpuRoot > donner::geode::SelectGpuRoot

(

const GpuRootSelection &

options

)

In WebAssembly builds, opens the browser's GPU device as a root. When the caller names no backend, halts if DONNER_GPU_BACKEND is invalid or names a native backend. A caller-named native backend halts when DONNER_GPU_BACKEND is non-empty and returns null otherwise. Also returns null when the device request fails.

Selects a native backend root for options and opens the system device behind it.

Halts the process when the Vulkan presentation options are inconsistent with each other or with the resolved backend. When the caller names no backend and DONNER_GPU_BACKEND controls selection, it also halts if the variable names no backend or one this process cannot open: an explicit process request is never silently replaced with another backend.

Parameters

options

Caller-supplied inputs.

Returns

The root, or null when a caller-named or platform-default backend cannot be opened or this build cannot serve it.