# Juliet\include\Core\HAL\Event\SystemEvent

## Source Files
- Header: `Juliet\include\Core\HAL\Event\SystemEvent.h`
- Source: `Juliet\src\Core\HAL\Event\SystemEvent.cpp`

## AI Description
The `SystemEvent` class in the Juliet library is designed to handle all events from systems responsible for hardware interactions, such as the display and keyboard/mouse. It provides a unified interface for retrieving and managing system events efficiently.

### Main Purpose:
- **Unifies Event Handling**: The class consolidates various types of system events into a single `SystemEvent` structure, making it easier to manage and process all events in a consistent manner.
- **Efficient Event Queue Management**: The use of a queue allows for efficient retrieval and processing of events without blocking the main thread. This is particularly useful in real-time applications where timely event handling is crucial.

### Design:
1. **Event Types**:
   - `EventType`: A simple enumeration that defines different types of system events, such as application exit, window close request, key down/up, mouse move/button press/release.
   - `WindowEvent`, `KeyboardEvent`, `MouseMovementEvent`, and `MouseButtonEvent`: Structs that encapsulate specific details about each type of event, including the associated window ID, keyboard/mouse ID, key state, button state, etc.

2. **Union for All System Events**:
   - `AllSystemEventUnion`: A tagged union that can hold any of the above event types along with additional data if needed. This ensures that all events are handled uniformly and efficiently.
   - `Padding`: An array of bytes to make sure the union is fixed in size and big enough on all platforms.

3. **Event Queue**:
   - `eventQueue`: A static queue that stores system events. The queue is used to retrieve events from the main thread without blocking, allowing for efficient event handling in real-time applications.
   - `PumpEvents()`: A helper function that updates all systems' event loops and gathers events into the main queue.

4. **Event Retrieval Functions**:
   - `GetEvent(SystemEvent? event)`: Retrieves an event from the queue if available, otherwise returns false.
   - `WaitEvent(SystemEvent? event, int32 timeoutInNS = -1)`: Waits for an event to be available in the queue within a specified time period. If no event is available, it returns false.

### Usage:
To use the `SystemEvent` class, you can simply include the header file and call the appropriate functions to retrieve or wait for events. This ensures that all system events are handled consistently and efficiently, making it easier to manage and respond to hardware interactions in your applications.

## Symbols

### Namespace `Juliet`

#### Classes, Structs & Unions
- `struct WindowEvent`
- `struct KeyboardEvent`
- `struct MouseMovementEvent`
- `struct MouseButtonEvent`
- `union AllSystemEventUnion`
- `struct SystemEvent`

#### Enums
- `enum class EventType`

#### Functions & Methods
- `// Make sure we do not bust the union size static_assert(sizeof(AllSystemEventUnion) == sizeof(((AllSystemEventUnion*)nullptr)->Padding))`
- `// Poll for any event, return false if no event is available.
    // Equivalent to WaitEvent(event, 0);
    // Will not block
    extern JULIET_API bool GetEvent(SystemEvent& event)`
- `// TODO : use chrono to tag the timeout correctly with nanosec
    // timeout == -1 means wait for any event before pursuing
    // timeout == 0 means checking once for the frame and getting out
    // timeout > 0 means wait until time is out
    extern JULIET_API bool WaitEvent(SystemEvent& event, int32 timeoutInNS = -1)`
- `// Add an event onto the event queue.
    // TODO : support array of events
    extern JULIET_API bool AddEvent(SystemEvent& event)`

