ludus::platform::HostedWindowEndpoint

Ludus Wiki · API overview · Browse API

Class

Editor-side endpoint of one hosted-window session.

Start() creates a private directory (mode 0700) inside a caller-chosen parent, listens on a Unix stream socket in it and draws a 32-byte random token. Pass GetChannelAddress() to the game process as HOSTED_WINDOW_ENVIRONMENT_VARIABLE. Pump() admits at most one window: the peer must run under this process's user id and present the token and protocol version in its first message. Once a window is admitted the socket file is removed, so no further process can connect. Refused peers are disconnected and counted; the endpoint keeps listening for the real window.

The Send calls mirror the native window vocabulary: extent in backing pixels plus scale, visibility, focus enter (with the held-key baseline) and loss, physical key transitions and close. Stop() or destruction closes the channel, which the window reports as a close.

All I/O is nonblocking and bounded; no call waits for the game. The endpoint owns no toolkit objects and has no thread affinity, but it is not synchronized: use one instance from one thread at a time. Available on macOS and Linux; elsewhere Start() returns Unavailable.

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

#include <ludus/platform/hosted_window.h>

class ludus::platform::HostedWindowEndpoint final

Related declarations

• ludus::platform::HostedWindowEndpoint::StartInfo

Methods

HostedWindowEndpoint

ludus::platform::HostedWindowEndpoint::HostedWindowEndpoint() noexcept

Construct a stopped endpoint. Does not allocate.

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

~HostedWindowEndpoint

ludus::platform::HostedWindowEndpoint::~HostedWindowEndpoint() noexcept

Stop the session, closing the channel and removing its directory.

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

HostedWindowEndpoint

ludus::platform::HostedWindowEndpoint::HostedWindowEndpoint(const HostedWindowEndpoint &)=delete

Not copyable: one endpoint owns the session's socket, directory and token.

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

operator=

HostedWindowEndpoint & ludus::platform::HostedWindowEndpoint::operator=(const HostedWindowEndpoint &)=delete

Not copyable: one endpoint owns the session's socket, directory and token.

Related types: HostedWindowEndpoint

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

HostedWindowEndpoint

ludus::platform::HostedWindowEndpoint::HostedWindowEndpoint(HostedWindowEndpoint &&)=delete

Not movable: the editor keeps one endpoint per session in place for its lifetime.

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

operator=

HostedWindowEndpoint & ludus::platform::HostedWindowEndpoint::operator=(HostedWindowEndpoint &&)=delete

Not movable: the editor keeps one endpoint per session in place for its lifetime.

Related types: HostedWindowEndpoint

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

Start

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::Start(const StartInfo &info) noexcept

Create the session directory, socket and token, and start listening.

Parameter	Description
info	Session parameters; the initial state reaches the window in its Welcome.

Returns

Ok and state Listening; InvalidState when already started; InvalidArgument for a relative, empty or overlong parent or an invalid initial state; OutOfMemory or Unavailable on resource failure. On failure the endpoint stays Stopped and leaves no directory behind.

Related types: HostedEndpointStatus · StartInfo

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

Stop

void ludus::platform::HostedWindowEndpoint::Stop() noexcept

End the session: close the channel, remove the socket and directory.

A connected window observes channel loss and reports a close. Safe to call when stopped. The endpoint can be started again afterwards.

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

GetChannelAddress

std::string_view ludus::platform::HostedWindowEndpoint::GetChannelAddress() const noexcept

Channel address to publish in HOSTED_WINDOW_ENVIRONMENT_VARIABLE.

Format "1:<64 hexadecimal token digits>:<absolute socket path>". The view points into the endpoint and stays valid until Stop() or destruction. It is a secret for the session: pass it only to the child's environment.

Returns

The address, or an empty view when stopped.

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

GetDirectory

std::string_view ludus::platform::HostedWindowEndpoint::GetDirectory() const noexcept

Absolute path of the private session directory, or empty when stopped.

Valid until Stop() or destruction. Provided so callers can report or verify the location; the endpoint removes the directory itself.

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

GetState

HostedConnectionState ludus::platform::HostedWindowEndpoint::GetState() const noexcept

Current connection state.

Related types: HostedConnectionState

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

GetLastRefusal

HostedRefusal ludus::platform::HostedWindowEndpoint::GetLastRefusal() const noexcept

Reason for the most recent refusal, or None.

Related types: HostedRefusal

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

GetRefusalCount

foundation::uint32 ludus::platform::HostedWindowEndpoint::GetRefusalCount() const noexcept

Number of peers refused since Start().

Related types: foundation::uint32

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

Pump

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::Pump() noexcept

Admit a pending window, progress its handshake, flush queued messages and detect disconnection.

Call regularly, for example once per editor frame. A handshake that does not complete within 5 seconds of the connection is refused as HandshakeTimeout.

Returns

Ok while the session runs (Listening or Connected); NotConnected after the window disconnected; InvalidState when stopped.

Related types: HostedEndpointStatus

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

SendResize

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::SendResize(foundation::uint32 width, foundation::uint32 height, foundation::float32 scale) noexcept

Publish a new extent in backing pixels and scale.

Returns

Ok, NotConnected (recorded for the Welcome), Overflow, InvalidArgument or InvalidState.

Related types: foundation::float32 · foundation::uint32 · HostedEndpointStatus

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

SendVisibility

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::SendVisibility(WindowVisibility visibility) noexcept

Publish a visibility change; Minimized makes the window publish a zero extent.

Returns

Ok, NotConnected (recorded for the Welcome), Overflow, InvalidArgument or InvalidState.

Related types: HostedEndpointStatus · WindowVisibility

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

SendFocusEntered

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::SendFocusEntered(const input::FocusBaseline &baseline) noexcept

Give the window keyboard focus with the keys currently held.

The window delivers a FocusEntered reset carrying this baseline without press edges, as Cocoa and Wayland do. Calling it again while focused replaces the baseline. Invalid key slots in baseline are ignored.

Returns

Ok, NotConnected (recorded for the Welcome), Overflow or InvalidState.

Related types: HostedEndpointStatus · input::FocusBaseline

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

SendFocusLost

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::SendFocusLost() noexcept

Take keyboard focus away; the window delivers a FocusLost reset. No-op when unfocused.

Returns

Ok, NotConnected (recorded for the Welcome), Overflow or InvalidState.

Related types: HostedEndpointStatus

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

SendKey

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::SendKey(input::Key key, input::KeyTransition transition, bool isRepeat) noexcept

Deliver one physical key transition to the focused window.

Parameter	Description
key	A valid physical key, usually from MapCocoaKeyCode() or MapEvdevKeyCode().
transition	Down or Up.
isRepeat	True for an operating-system auto-repeat Down.

Returns

Ok; NotConnected (dropped); InvalidState without focus; InvalidArgument for an invalid key; Overflow.

Related types: input::Key · input::KeyTransition · HostedEndpointStatus

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

SendClose

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::SendClose() noexcept

Ask the window to close, as clicking a native close button would.

The window reports the close from its next HandleEvent(). Later Send calls return InvalidState.

Returns

Ok, NotConnected (recorded for the Welcome), Overflow or InvalidState.

Related types: HostedEndpointStatus

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

TryTakeSurfaceEvent

bool ludus::platform::HostedWindowEndpoint::TryTakeSurfaceEvent(HostedSurfaceEvent &outEvent) noexcept

Take the oldest hosted surface message the window sent.

Pump() receives them: an Images event carries a new generation and owns its sharing handles (Mach send rights received through the session's Mach rendezvous on macOS, file descriptors received with SCM_RIGHTS); a Present event names a completed image. Events keep their arrival order. At most eight are queued; until they are taken, the endpoint stops reading the window, which then sees its surface calls report Busy. Disconnection discards queued events.

Parameter	Description
outEvent	The event; unchanged unless true is returned.

Returns

true when an event was taken.

Related types: HostedSurfaceEvent

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

SendRelease

HostedEndpointStatus ludus::platform::HostedWindowEndpoint::SendRelease(foundation::uint32 generation, foundation::uint32 image) noexcept

Return a presented image to the window once the consumer's sampling has completed.

A release is never dropped: when the send queue is full it waits, in order, and is sent once the queue drains.

Parameter	Description
generation	Generation of the released image.
image	Index of the released image in that generation.

Returns

Ok; NotConnected; InvalidArgument for a zero generation or an index outside the generation; InvalidState when stopped; Overflow when twelve releases are already waiting.

Related types: foundation::uint32 · HostedEndpointStatus

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