Skip to main content

PassCommitListener.ixx File

Interface for listeners notified when a pass commits its state. More...

Included Headers​

#include <helios.engine.runtime.world.UpdateContext> #include <helios.engine.runtime.world.GameWorld> #include <helios.engine.runtime.gameloop.CommitPoint>

Namespaces Index​

namespacehelios
namespaceengine

Main engine module aggregating core infrastructure and game systems. More...

namespaceruntime

Runtime infrastructure for game execution and lifecycle orchestration. More...

namespacegameloop

Central game loop orchestration module. More...

Classes Index​

classPassCommitListener

Interface for receiving notifications when a pass reaches its commit point. More...

Description​

Interface for listeners notified when a pass commits its state.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file PassCommitListener.ixx
3 * @brief Interface for listeners notified when a pass commits its state.
4 */
5module;
6
7
8export module helios.engine.runtime.gameloop.PassCommitListener;
9
10import helios.engine.runtime.gameloop.CommitPoint;
11
12import helios.engine.runtime.world.GameWorld;
13import helios.engine.runtime.world.UpdateContext;
14
15using namespace helios::engine::runtime::world;
16
17export namespace helios::engine::runtime::gameloop {
18
19 /**
20 * @brief Interface for receiving notifications when a pass reaches its commit point.
21 *
22 * @details
23 * The PassCommitListener provides a callback mechanism for responding to pass-level
24 * synchronization events within the game loop. When a Pass has a configured CommitPoint
25 * and finishes execution, registered listeners are notified via `onPassCommit()`.
26 *
27 * This interface is primarily implemented by the GameLoop class to handle:
28 * - **Event buffer swapping:** Making pass-level events readable to subsequent passes.
29 * - **Command flushing:** Executing deferred commands from the CommandBuffer.
30 * - **Manager flushing:** Processing queued requests (e.g., spawn/despawn operations).
31 *
32 * The CommitPoint flags determine which synchronization actions are performed:
33 *
34 * | Flag | Action |
35 * |------|--------|
36 * | `PassEvents` | Swaps pass event bus buffers |
37 * | `FlushCommands` | Executes pending commands |
38 * | `FlushManagers` | Processes manager requests |
39 * | `Structural` | Combines all three flags |
40 *
41 * @par Integration with GameLoop
42 *
43 * The GameLoop implements this interface and registers itself with each Phase.
44 * When a Pass with a commit point completes, the Phase calls `onPassCommit()`,
45 * allowing the GameLoop to perform the appropriate synchronization.
46 *
47 * ```cpp
48 * // In GameLoop::onPassCommit():
49 * if ((commitPoint & CommitPoint::PassEvents) == CommitPoint::PassEvents) {
50 * passEventBus_.swapBuffers();
51 * }
52 * if ((commitPoint & CommitPoint::FlushCommands) == CommitPoint::FlushCommands) {
53 * commandBuffer_.flush(updateContext.gameWorld());
54 * }
55 * if ((commitPoint & CommitPoint::FlushManagers) == CommitPoint::FlushManagers) {
56 * updateContext.gameWorld().flushManagers(updateContext);
57 * }
58 * ```
59 *
60 * @see GameLoop
61 * @see Phase
62 * @see Pass
63 * @see CommitPoint
64 */
65 class PassCommitListener {
66
67
68 public:
69
70 /**
71 * @brief Virtual destructor for proper polymorphic cleanup.
72 */
73 virtual ~PassCommitListener() = default;
74
75 /**
76 * @brief Called when a pass reaches its commit point.
77 *
78 * @details
79 * Implementations should check the CommitPoint flags and perform the
80 * appropriate synchronization actions. The order of operations should be:
81 *
82 * 1 **PassEvents** - Swap event buffers first so subsequent actions can emit events.
83 * 2 **FlushCommands** - Execute commands before managers to generate spawn requests.
84 * 3 **FlushManagers** - Process requests after commands have been executed.
85 *
86 * @param commitPoint The flags specifying which synchronization actions to perform.
87 * @param gameWorld The game world for which the pass occurred.
88 * @param updateContext The current frame's update context.
89 *
90 * @note This method is marked `noexcept` as it is called during the game loop
91 * hot path and should not throw exceptions.
92 *
93 * @see CommitPoint
94 * @see Pass::addCommitPoint()
95 */
96 virtual void onPassCommit(
97 CommitPoint commitPoint,
98 GameWorld& gameWorld,
99 UpdateContext& updateContext) noexcept = 0;
100 };
101
102
103}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.