ludus::platform::HostedSurfaceChannel¶

Class

Producer side of the hosted surface channel, owned by a hosted window.

RHI reaches it through NativeWindowInfo::HostedSurfaceOrNull when it connects a device to a WindowSystem::Hosted window. The order of calls is: PublishImages() for a generation, then Present() for each completed frame of it, and TakeRelease() to learn which presented images the consumer has returned. Every call is nonblocking. Use it on the thread that pumps the window; it is not synchronized. The channel belongs to the window and is valid until the window is destroyed.

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

#include <ludus/platform/hosted_surface.h>

class ludus::platform::HostedSurfaceChannel

Methods¶

PublishImages¶

virtual HostedSurfaceStatus ludus::platform::HostedSurfaceChannel::PublishImages(HostedSurfaceImages &inoutImages) noexcept=0

Send a new generation to the consumer.

On macOS the Mach send rights travel through the session's Mach rendezvous and the description over the socket; on Linux the file descriptors travel with the description using SCM_RIGHTS.

Parameter	Description
`inoutImages`	Generation to publish. On Ok its handles are consumed and left empty; on any other result they stay owned by the caller.

Returns

Ok, Busy, Disconnected, InvalidArgument or Unavailable.

Related types: HostedSurfaceStatus · HostedSurfaceImages

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

Present¶

virtual HostedSurfaceStatus ludus::platform::HostedSurfaceChannel::Present(foundation::uint32 generation, foundation::uint32 image, foundation::uint64 sequence) noexcept=0

Announce one completed frame.

Precondition

The GPU work that wrote the image has completed; the consumer samples it without further waits.

Parameter	Description
`generation`	A published generation.
`image`	Image index in that generation.
`sequence`	Frame number, strictly increasing across the session.

Returns

Ok, Busy, Disconnected or InvalidArgument.

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

TakeRelease¶

virtual HostedSurfaceStatus ludus::platform::HostedSurfaceChannel::TakeRelease(HostedImageRelease &outRelease) noexcept=0

Take the oldest release the consumer has sent, receiving from the channel first.

Window events received on the way stay queued for the next HandleEvent(), in order.

Parameter	Description
`outRelease`	The release; unchanged unless Ok.

Returns

Ok, Busy when none is pending, or Disconnected.

Related types: HostedSurfaceStatus · HostedImageRelease

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

TryGetConsumerAdapter¶

virtual bool ludus::platform::HostedSurfaceChannel::TryGetConsumerAdapter(HostedAdapterIdentity &outAdapter) const noexcept=0

The adapter the consumer imports onto, when the endpoint announced one.

The endpoint sends it in the Welcome (HostedWindowEndpoint::StartInfo::ConsumerAdapterOrNull), so it is known as soon as the window exists and never changes. Vulkan RHI prefers the adapter with these UUIDs when it connects a device to the window. It is a preference, not a guarantee: without a matching adapter, RHI selects as usual and the consumer refuses the images.

Parameter	Description
`outAdapter`	The consumer's adapter; unchanged unless true is returned.

Returns

true when the endpoint announced an adapter.

Related types: HostedAdapterIdentity

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