Skip to content

ludus::platform

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/platform/include/ludus/platform/base/window.h

Enumerations

WindowVisibility

enum class WindowVisibility : ludus::foundation::uint8
Whether any part of a window can currently be seen.
A loop that should save power lowers its rate while a window is not Visible (docs/architecture/high-resolution-time.md, "Native frame pacing").

Related types: ludus::foundation::uint8

Visible

Visible
Some part of the window may be on screen, or the backend cannot tell.

Occluded

Occluded
The window is open but no part is on screen: fully covered by opaque windows, on another Space, or ordered out (including a hidden application). A closed window also reports Occluded.

Minimized

Minimized
The window is minimized (miniaturized into the Dock on macOS). Its published extent is zero.

Declared in modules/platform/include/ludus/platform/base/window.h

PacingWaitStatus

enum class PacingWaitStatus : foundation::uint8
Result of one wait request made through a PacingClock.

Related types: foundation::uint8

Completed

Completed
The wait returned after its requested interval. It may have returned late.

Interrupted

Interrupted
The wait returned early, for example after a signal. The pacer rereads the clock.

Unsupported

Unsupported
The target has no wait primitive. Browser builds always report this.

Failed

Failed
The operating system rejected the request.

Declared in modules/platform/include/ludus/platform/frame_pacing.h

PacingStatus

enum class PacingStatus : foundation::uint8
Configure() result.

Related types: foundation::uint8

Ok

Ok
The policy was applied and the schedule was dropped.

InvalidConfiguration

InvalidConfiguration
The interval was zero or longer than MAXIMUM_PACING_INTERVAL_NANOSECONDS; the previous policy and schedule are kept.

Declared in modules/platform/include/ludus/platform/frame_pacing.h

PaceOutcome

enum class PaceOutcome : foundation::uint8
What one FramePacer::Pace() call did.

Related types: foundation::uint8

Disabled

Disabled
The pacer has no interval (default construction). The clock was not read and nothing waited.

InvalidClock

InvalidClock
The clock functions were null. Nothing was read or waited and the schedule is unchanged.

Baseline

Baseline
No schedule existed (first call, after Reset() or Configure()). The frame starts now and anchors the schedule.

Waited

Waited
The frame was early. The pacer waited, rechecking after each wake, until the target was reached.

Late

Late
The frame reached its target with no wait, late by at most MaximumLateness (possibly zero). It starts at once; missed targets are skipped and the phase is kept.

Rescheduled

Rescheduled
The frame was later than MaximumLateness. It starts at once and the schedule is re-anchored at its start.

WaitFailed

WaitFailed
A wait reported Unsupported or Failed. The frame starts early; the phase is kept.

WaitLimit

WaitLimit
MAXIMUM_PACING_WAIT_ATTEMPTS waits all returned early. The frame starts early; the phase is kept.

ClockRegression

ClockRegression
The clock read below the previous reading, or the target was more than two intervals away. Nothing waited; the schedule is re-anchored at this reading.

Overflow

Overflow
The next target cannot be represented. Nothing waited and the schedule is dropped.

Declared in modules/platform/include/ludus/platform/frame_pacing.h

HostedImageFormat

enum class HostedImageFormat : foundation::uint8
Pixel encoding of hosted surface images.

Related types: foundation::uint8

Unknown

Unknown = 0
No format; never valid in an Images message.

Rgba8Unorm

Rgba8Unorm = 1
Four 8-bit unsigned normalized channels in R, G, B, A byte order, not sRGB-encoded.

Declared in modules/platform/include/ludus/platform/hosted_surface.h

HostedHandleKind

enum class HostedHandleKind : foundation::uint8
Kind of operating-system handle that shares one hosted image.

Related types: foundation::uint8

None

None = 0
No handle.

MachPort

MachPort = 1
macOS: a Mach send right from IOSurfaceCreateMachPort.

OpaqueFileDescriptor

OpaqueFileDescriptor = 2
Linux: an opaque file descriptor from vkGetMemoryFdKHR (VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT).

Declared in modules/platform/include/ludus/platform/hosted_surface.h

HostedSurfaceEventKind

enum class HostedSurfaceEventKind : foundation::uint8
Kind of a HostedSurfaceEvent.

Related types: foundation::uint8

Images

Images
A new generation: HostedSurfaceEvent::Images is set.

Present

Present
A completed frame: Generation, Image and Sequence are set.

Declared in modules/platform/include/ludus/platform/hosted_surface.h

HostedSurfaceStatus

enum class HostedSurfaceStatus : foundation::uint8
Result of a HostedSurfaceChannel operation.

Related types: foundation::uint8

Ok

Ok
Done. For TakeRelease(), a release was returned.

Busy

Busy
Nothing is available now (TakeRelease()), or the channel cannot accept the message without blocking. Nothing was sent or consumed; retry on a later frame.

Disconnected

Disconnected
The channel is closed or was lost. The window reports a close from its next HandleEvent().

InvalidArgument

InvalidArgument
An argument is out of range: zero generation or extent, an image index or handle kind the platform does not use, or a non-increasing sequence.

Unavailable

Unavailable
The endpoint offers no transport for the handle kind (no Mach rendezvous, or a target without file-descriptor passing).

Declared in modules/platform/include/ludus/platform/hosted_surface.h

HostedRefusal

enum class HostedRefusal : foundation::uint8
Why an endpoint refused a connecting window.

Related types: foundation::uint8

None

None
No refusal.

WrongUser

WrongUser
The peer process runs under another user id.

BadToken

BadToken
The Hello carried a token other than this session's.

IncompatibleVersion

IncompatibleVersion
The Hello carried another protocol version or key-vocabulary size.

MalformedHello

MalformedHello
The first message was not a well-formed Hello.

HandshakeTimeout

HandshakeTimeout
No complete Hello arrived within the handshake timeout.

Declared in modules/platform/include/ludus/platform/hosted_window.h

HostedConnectionState

enum class HostedConnectionState : foundation::uint8
Connection state of a HostedWindowEndpoint.

Related types: foundation::uint8

Stopped

Stopped
Not started, stopped, or Start() failed.

Listening

Listening
The socket accepts connections; no window has been admitted yet.

Connected

Connected
One authenticated window is connected. The socket no longer accepts connections.

Disconnected

Disconnected
The admitted window disconnected or violated the protocol. The session is over.

Declared in modules/platform/include/ludus/platform/hosted_window.h

HostedEndpointStatus

enum class HostedEndpointStatus : foundation::uint8
Result of a HostedWindowEndpoint operation.

Related types: foundation::uint8

Ok

Ok
Done. For a Send call, the message is queued for the connected window.

NotConnected

NotConnected
No window is connected. A state change (extent, visibility, focus, close) is still recorded and reaches the window when it is admitted; a key is dropped.

Overflow

Overflow
The window has not drained the bounded send queue, so this message was dropped. Once the queue drains, the endpoint sends the current extent and visibility, an Overflow reset and the current focus baseline.

InvalidArgument

InvalidArgument
An argument is out of range: a zero or overlong path, an extent above the protocol limit, a non-finite or non-positive scale, an invalid key or visibility.

InvalidState

InvalidState
The call does not apply now: the endpoint is stopped or already started, a key was sent without focus, or a message followed SendClose().

Unavailable

Unavailable
The target has no hosted-window support (browser, Windows) or the operating system refused a directory or socket operation.

OutOfMemory

OutOfMemory
The endpoint could not allocate its session state, or system entropy for the token was unavailable.

Declared in modules/platform/include/ludus/platform/hosted_window.h

WindowSystem

enum class WindowSystem : ludus::foundation::uint8

Related types: ludus::foundation::uint8

Headless

Headless

Wayland

Wayland

WebCanvas

WebCanvas

Cocoa

Cocoa
Native macOS window and content view, owned by the Cocoa platform backend.

Hosted

Hosted
Window whose events come from a host channel (HOSTED_WINDOW_ENVIRONMENT_VARIABLE).
It has no native handles. RHI renders into the hosted surface reached through NativeWindowInfo::HostedSurfaceOrNull; see docs/architecture/editor-gui-systems.md, "The hosted surface and frame ownership".

Win32

Win32
Native Windows top-level window, owned by the Win32 platform backend.
NativeWindowInfo::Win32WindowOrNull carries its HWND; Width/Height are client-area pixels.

Declared in modules/platform/include/ludus/platform/native_window.h

Aliases

Window

using ludus::platform::Window = WindowBase

Related types: WindowBase

Declared in modules/platform/include/ludus/platform/base/window.h

Constants and variables

MAXIMUM_PACING_INTERVAL_NANOSECONDS

constexpr foundation::uint64 ludus::platform::MAXIMUM_PACING_INTERVAL_NANOSECONDS = foundation::time::NANOSECONDS_PER_SECOND
Longest pacing interval Configure() accepts: one second. One Pace() call never requests more than two intervals of waiting, so a misconfigured or regressed clock can never block the frame loop for longer than two seconds.

Related types: foundation::uint64

Declared in modules/platform/include/ludus/platform/frame_pacing.h

MAXIMUM_PACING_WAIT_ATTEMPTS

constexpr foundation::uint32 ludus::platform::MAXIMUM_PACING_WAIT_ATTEMPTS = 8
Operating-system waits one Pace() call may issue before it gives up and starts the frame early. Bounds the loop when a wait keeps returning before its target.

Related types: foundation::uint32

Declared in modules/platform/include/ludus/platform/frame_pacing.h

HOSTED_SURFACE_IMAGE_COUNT

constexpr foundation::usize ludus::platform::HOSTED_SURFACE_IMAGE_COUNT = 3
Images in each hosted surface generation.

Related types: foundation::usize

Declared in modules/platform/include/ludus/platform/hosted_surface.h

HOSTED_ADAPTER_UUID_BYTES

constexpr foundation::usize ludus::platform::HOSTED_ADAPTER_UUID_BYTES = 16
Bytes of a Vulkan deviceUUID or driverUUID (VK_UUID_SIZE).

Related types: foundation::usize

Declared in modules/platform/include/ludus/platform/hosted_surface.h

HOSTED_WINDOW_ENVIRONMENT_VARIABLE

constexpr char ludus::platform::HOSTED_WINDOW_ENVIRONMENT_VARIABLE[][] = "LUDUS_HOSTED_WINDOW"
Environment variable that selects the hosted window backend.
Its value is the channel address that HostedWindowEndpoint::GetChannelAddress() returns. When the variable is present, WindowManager::Initialize() and WindowManager::CreateWindow() use the hosted backend and never open a native window; an invalid value or a refused connection makes them fail instead of falling back. When it is absent, the native backend runs unchanged. It is a zero-terminated character array so it can be passed to both std::string_view and C environment APIs.

Declared in modules/platform/include/ludus/platform/hosted_window.h

LOG_PLATFORM

constexpr ludus::foundation::logging::LogCategory ludus::platform::LOG_PLATFORM {"Platform"}
Logging category for the platform layer (windowing, display server integration).
Engine modules declare their own categories at namespace scope so the id is computed at compile time (see FoundationLogging).

Related types: ludus::foundation::logging::LogCategory

Declared in modules/platform/include/ludus/platform/log_categories.h

Functions

TryFillSystemEntropy

bool ludus::platform::TryFillSystemEntropy(foundation::uint8 *outBytes, foundation::usize size) noexcept
Fill a buffer with cryptographically secure random bytes from the operating system.
macOS and Linux call getentropy(3) in requests of at most 256 bytes, its per-call limit. Windows uses the system-preferred CNG generator with the same request bound. Browser builds call Web Crypto crypto.getRandomValues (the global Web Crypto object under Node) in requests of the same size; a missing or throwing Web Crypto object reports failure instead of raising a JavaScript exception. Other targets have no adapter yet and fail every nonempty request. There is never a fallback to wall time, addresses, rand or a pseudo-random generator.
Thread-safe and allocation-free. Linux may block briefly during early boot until the kernel entropy pool is initialized; call it outside latency-critical frame work.
ParameterDescription
outBytes
Destination for size bytes; must be nonnull (null reports failure).
size
Number of bytes to write; zero succeeds without an operating-system call.

Returns

true when all size bytes were written; false when entropy is unavailable. On failure the destination contents are unspecified and must not be used.

Related types: foundation::uint8 · foundation::usize

Declared in modules/platform/include/ludus/platform/entropy.h

GetSystemEntropySource

foundation::identity::EntropySource ludus::platform::GetSystemEntropySource() noexcept
Return the production entropy source for foundation::identity::TryGenerateUuidV4().
The source calls TryFillSystemEntropy() and carries no context or state, so it may be copied, stored and used concurrently from any thread. A failure is reported by TryGenerateUuidV4() as UuidStatus::EntropyUnavailable with its output unchanged.

Returns

A source whose FillBytesOrNull is never null.

Related types: foundation::identity::EntropySource

Declared in modules/platform/include/ludus/platform/entropy.h

GetSystemPacingClock

PacingClock ludus::platform::GetSystemPacingClock() noexcept
Return the native pacing clock: FoundationTime Now() and a relative operating-system wait.
Each wait covers the interval remaining until the target, computed from a fresh Now() reading on every attempt. The absolute target therefore stays in the FoundationTime domain and lateness never accumulates across frames. macOS waits on a one-shot kevent64(2) timer marked NOTE_CRITICAL, which opts out of the kernel's timer-coalescing leeway (up to 1 ms for a windowed application and several milliseconds for a background process on the measured host); if the thread's queue cannot be created it falls back to nanosleep(2). Linux sleeps with nanosleep(2). Windows uses a one-shot relative waitable timer, preferring high resolution and falling back to regular resolution. A wake can still be late by scheduler latency, and on Linux by timer slack. A signal returns Interrupted. Browser builds return a clock whose wait always reports Unsupported: browsers pace with presentation callbacks and must never block or busy-wait. Other targets have no adapter and also report Unsupported.
The returned value carries no state, so it may be copied and used from any thread. Windows and macOS waiting threads lazily acquire a timer handle or kqueue descriptor and release it when they exit.

Note

Zero leeway keeps the kernel from batching this wake with other timers. A loop that should save power while hidden or idle lowers its pacing rate.

Returns

A clock whose function pointers are never null and whose context is null.

Related types: PacingClock

Declared in modules/platform/include/ludus/platform/frame_pacing.h

MapCocoaKeyCode

input::Key ludus::platform::MapCocoaKeyCode(foundation::uint32 keyCode) noexcept
Map a macOS virtual key code to the physical Ludus key the Cocoa backend publishes.
This is the table behind the Cocoa window's keyboard records and focus baselines, so a code converted here names the same key a native Cocoa window would report. Codes are hardware positions (NSEvent.keyCode, the kVK_* constants of HIToolbox/Events.h), not characters, and are layout-independent. Qt reports this code as QKeyEvent::nativeVirtualKey() on macOS.
Available on every target: the table is plain data with no AppKit dependency. Thread-safe and allocation-free.
ParameterDescription
keyCode
Native virtual key code.

Returns

The mapped key; Key::Unknown for a code the Cocoa backend does not map (Fn, media, ISO/JIS-only and keypad-equals positions) or that is out of range.

Related types: foundation::uint32 · input::Key

Declared in modules/platform/include/ludus/platform/native_keymap.h

MapEvdevKeyCode

input::Key ludus::platform::MapEvdevKeyCode(foundation::uint32 code) noexcept
Map a Linux evdev key code to the physical Ludus key the Wayland backend publishes.
This is the table behind wl_keyboard.key and wl_keyboard.enter normalization. The code uses <linux/input-event-codes.h> numbering. An XKB keycode is the evdev code plus 8: Qt's QKeyEvent::nativeScanCode() on xcb and Wayland is an XKB keycode, so subtract 8 before calling. No keysym or layout lookup is performed.
Declared on Linux only, because the table is built from the Linux input-event header. Thread-safe and allocation-free.
ParameterDescription
code
Native evdev key code.

Returns

The mapped key; Key::Unknown for an unmapped, vendor or out-of-range code.

Related types: foundation::uint32 · input::Key

Declared in modules/platform/include/ludus/platform/native_keymap.h