RealmOA Library

oa::Presenter

surface ownership normally stays with the caller. call close() or detachPresentation() before destroying the surface. as misuse containment, destroying an attached presenter transfers the surface and WSI state to the engine; the engine destroys them at close() and the caller must not do so.

ClC++ public headers

Public Types

St
St

Public Methods

bool oa::Presenter::acquireSwapchainImage(Swapchain & inSwap, AcquireResult & outResult)
oavk::Stream * oa::Presenter::activeGraphicsBatchStream()
oa::Status oa::Presenter::beginGraphicsBatch()
void oa::Presenter::beginImGuiFrame()
oa::Status oa::Presenter::close()
oa::Result<void *> oa::Presenter::createSurface(const VulkanWindow & inWindow)
oa::Status oa::Presenter::destroySurface(void *& inOutSurface)
void oa::Presenter::detachPresentation()
bool oa::Presenter::drawFrame()
void oa::Presenter::endImGuiFrame()
oa::Engine & oa::Presenter::engine()
oa::Result<oa::Event> oa::Presenter::flushGraphicsBatch(const oa::Event & inProducer = = {})
VkRenderPass oa::Presenter::getRenderPass()
bool oa::Presenter::hasGraphics()
bool oa::Presenter::hasPresent()
bool oa::Presenter::initImGui(void * inNativeWindow)
bool oa::Presenter::initPresentation(void * inSurface, VkExtent2D inExtent)
bool oa::Presenter::isImGuiReady()
bool oa::Presenter::isPresentationReady()
void oa::Presenter::lockSharedQueueSubmit(void * inQueue)
void oa::Presenter::notifyPixelSizeChanged(int inWidthPx, int inHeightPx)
bool oa::Presenter::presentSwapchainImage(Swapchain & inSwap, oa::U32 inImageIndex, oa::U32 inFrameSlot, const PresentArgs & inArgs)
bool oa::Presenter::recreateSwapchain(VkExtent2D inNewExtent)
void oa::Presenter::shutdownImGui()
Swapchain & oa::Presenter::swapchain()
const Swapchain & oa::Presenter::swapchain()
VkExtent2D oa::Presenter::swapchainExtent()
VkFormat oa::Presenter::swapFormat()
oa::Status oa::Presenter::syncGraphicsBatch()
void oa::Presenter::unlockSharedQueueSubmit(void * inQueue)
bool oa::Presenter::usesMergedGraphicsComputeQueue()
oa::Status oa::Presenter::waitPresentationIdle()

Constructor & Destructor Documentation

oa::Presenter::Presenter( oa::Engine & inEngine )
No public source comment is attached to this declaration.

Parameters

inEngine
oa::Engine &

—

void oa::Presenter::~Presenter()
No public source comment is attached to this declaration.

Public Method Documentation

bool oa::Presenter::acquireSwapchainImage( Swapchain & inSwap, AcquireResult & outResult )
acquire the next swapchain image. Waits the inFlightFence at the current frameIndex, calls vkAcquireNextImageKHR signalling imageAvailSem[frameIndex], populates outResult. Returns false on hard error (surface lost, zero-size window).

Parameters

inSwap
Swapchain &

—

outResult
AcquireResult &

—

Returns

bool

The declared return value.

oavk::Stream * oa::Presenter::activeGraphicsBatchStream()
No public source comment is attached to this declaration.

Returns

oavk::Stream *

The declared return value.

oa::Status oa::Presenter::beginGraphicsBatch()
Unified graphics/compute frame batch recorded on the graphics queue. Graphics queues also support compute, so Render canvas draws and oa::Ui compute composition can share one command buffer and timeline edge. flush returns the exact submission event consumed by presentation resources.

Returns

oa::Status

The declared return value.

void oa::Presenter::beginImGuiFrame()
Per-frame ImGui — no-ops without OA_IMGUI.

Returns

void

The declared return value.

oa::Status oa::Presenter::close()
No public source comment is attached to this declaration.

Returns

oa::Status

The declared return value.

oa::Result<void *> oa::Presenter::createSurface( const VulkanWindow & inWindow )
Create/destroy a caller-owned opaque WSI surface through a window backend. The vulkan instance never leaves the runtime boundary. detach presentation before destroying an attached surface.

Parameters

inWindow
const VulkanWindow &

—

Returns

oa::Result<void *>

The declared return value.

oa::Status oa::Presenter::destroySurface( void *& inOutSurface )
No public source comment is attached to this declaration.

Parameters

inOutSurface
void *&

—

Returns

oa::Status

The declared return value.

void oa::Presenter::detachPresentation()
Tear down swapchain-dependent resources, clear surface_. call BEFORE vkDestroySurfaceKHR on the old surface.

Returns

void

The declared return value.

bool oa::Presenter::drawFrame()
acquire → record (clear + optional ImGui) → submit → present.

Returns

bool

The declared return value.

void oa::Presenter::endImGuiFrame()
No public source comment is attached to this declaration.

Returns

void

The declared return value.

oa::Engine & oa::Presenter::engine()
No public source comment is attached to this declaration.

Returns

oa::Engine &

The declared return value.

oa::Result<oa::Event> oa::Presenter::flushGraphicsBatch( const oa::Event & inProducer = = {} )
No public source comment is attached to this declaration.

Parameters

inProducer
const oa::Event &

Default: = {}

Returns

oa::Result<oa::Event>

The declared return value.

VkRenderPass oa::Presenter::getRenderPass()
No public source comment is attached to this declaration.

Returns

VkRenderPass

The declared return value.

bool oa::Presenter::hasGraphics()
No public source comment is attached to this declaration.

Returns

bool

The declared return value.

bool oa::Presenter::hasPresent()
No public source comment is attached to this declaration.

Returns

bool

The declared return value.

bool oa::Presenter::initImGui( void * inNativeWindow )
phase-D: ImGui SDL3 backend init. compile with -DOA_IMGUI to activate. inNativeWindow — SDL_Window* from oa::VulkanWindow::getNativeWindowHandle(). Without OA_IMGUI: returns true immediately (no-op).

Parameters

inNativeWindow
void *

—

Returns

bool

The declared return value.

bool oa::Presenter::initPresentation( void * inSurface, VkExtent2D inExtent )
phase-C: attach surface, build swapchain + renderpass + sync. Safe to call again after detachPresentation() with a new surface.

Parameters

inSurface
void *

—

inExtent
VkExtent2D

—

Returns

bool

The declared return value.

bool oa::Presenter::isImGuiReady()
No public source comment is attached to this declaration.

Returns

bool

The declared return value.

bool oa::Presenter::isPresentationReady()
No public source comment is attached to this declaration.

Returns

bool

The declared return value.

void oa::Presenter::lockSharedQueueSubmit( void * inQueue )
Compatibility spelling for presentation/ImGui callbacks that must surround a raw vulkan queue operation. It selects the centralized mutex for the exact compute, graphics, or present queue handle, including distinct queues.

Parameters

inQueue
void *

—

Returns

void

The declared return value.

void oa::Presenter::notifyPixelSizeChanged( int inWidthPx, int inHeightPx )
call from the window's SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED handler. DrawFrame will recreate the swapchain at the top of the next frame.

Parameters

inWidthPx
int

—

inHeightPx
int

—

Returns

void

The declared return value.

bool oa::Presenter::presentSwapchainImage( Swapchain & inSwap, oa::U32 inImageIndex, oa::U32 inFrameSlot, const PresentArgs & inArgs )
Build a one-off graphics command buffer per the body described above, then submit on the graphics queue waiting on imageAvailSem[inFrameSlot], signalling renderDoneSem[inFrameSlot] with inFlightFence[inFrameSlot]; call vkQueuePresentKHR waiting on renderDoneSem[inFrameSlot]. Advances Swapchain.frameIndex on success.

Parameters

inSwap
Swapchain &

—

inImageIndex
oa::U32

—

inFrameSlot
oa::U32

—

inArgs
const PresentArgs &

—

Returns

bool

The declared return value.

bool oa::Presenter::recreateSwapchain( VkExtent2D inNewExtent )
Explicit swapchain resize (DrawFrame handles OUT_OF_DATE automatically).

Parameters

inNewExtent
VkExtent2D

—

Returns

bool

The declared return value.

void oa::Presenter::shutdownImGui()
No public source comment is attached to this declaration.

Returns

void

The declared return value.

Swapchain & oa::Presenter::swapchain()
No public source comment is attached to this declaration.

Returns

Swapchain &

The declared return value.

const Swapchain & oa::Presenter::swapchain()
Direct access to the swapchain (FinalGlue §3.5). Returns a reference to the engine-owned oa::Swapchain; zero-state when no surface is attached. Use isPresentationReady() / swapchain().isValid() to gate.

Returns

const Swapchain &

The declared return value.

VkExtent2D oa::Presenter::swapchainExtent()
No public source comment is attached to this declaration.

Returns

VkExtent2D

The declared return value.

VkFormat oa::Presenter::swapFormat()
No public source comment is attached to this declaration.

Returns

VkFormat

The declared return value.

oa::Status oa::Presenter::syncGraphicsBatch()
No public source comment is attached to this declaration.

Returns

oa::Status

The declared return value.

void oa::Presenter::unlockSharedQueueSubmit( void * inQueue )
No public source comment is attached to this declaration.

Parameters

inQueue
void *

—

Returns

void

The declared return value.

bool oa::Presenter::usesMergedGraphicsComputeQueue()
True when graphicsQueue and computeQueue are the same vkQueue (common on laptops).

Returns

bool

The declared return value.

oa::Status oa::Presenter::waitPresentationIdle()
WSI completion is not implied by the render-submission timeline. Until a present-id/fence path is enabled, this is the narrow explicit boundary for destroying presentation-owned resources.

Returns

oa::Status

The declared return value.