| CRM64Pro GDK v0.19.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Main
Core modules

## Description

Central hub for CRM64Pro GDK initialization, module access and high-precision timing [v26.06.1].

### Overview

The Main module serves as the central entry point and orchestrator for the CRM64Pro Game Development Kit. It manages the complete lifecycle of the application, from system initialization through shutdown, while providing unified access to all other GDK modules.

### Key features

- System initialization and graceful shutdown of CRM64Pro
- Unified event handling and update system
- High-Precision canonical game loop: Uses nanosecond-resolution performance counters and integer accumulators to ensure zero-drift timing and deterministic simulation.
- Smooth Interpolation: Provides alpha values for sub-pixel rendering, eliminating jitter on high-refresh-rate displays.
- Keyboard input system management
- Centralized access point to all GDK modules

### Module access

Core | Log • Config • Timer • Tool
Data | Archive • XML
Audio | Audio Track
Graphics | Image • Cursor • Tile • Sprite • Font • GFX • Physics • Video • Particle
GUI | GUI • Widgets
Tile engine | Scene Core • Scene TileLayer
Network | TCP/IP

### Module types

The GDK provides two module complexity levels, allowing simple utilities to coexist with feature-rich systems:

Standard | Simple module with a few methods that may or may not be related
Advanced | Complex module with several interconnected methods

### Manager types

Managers handle object lifecycle and resource sharing. Each manager follows one of these patterns based on its resource requirements:

Standard | Objects must be unique by name; creation fails if name exists
Sharing | Returns shared ID for existing objects; control methods affect all shared instances
Cloning | Creates independent copies sharing base data; loaded duplicates auto-clone

### Return value conventions

- Handle-returning methods: Return greater than 0 on success, or a negative error code on failure. 0 is reserved for default, none, all, or first-object semantics depending on the method.
- Status methods: Return 0 on success, or a negative error code on failure.
- Boolean methods: Return true on success or when the requested condition is true, and false on failure or when the condition is false.
- Return type selection: Use void only for direct state or callback assignment that cannot fail. Use bool for simple validation or condition results. Use Sint32 when an operation can fail for multiple reasons or touches SDL, files, archives, allocation, audio/video devices, or resource ownership.
- Count, index, size, scalar and enum methods: Document their valid range and sentinel values explicitly because 0 may be a valid result.
- Control methods: Return documented control codes when the return value drives the caller's flow instead of reporting status.
- Network result methods: Return ::NR_OK on success, or a negative ::eNetResult value on failure.

### Threading conventions

- All CRM64Pro managers, objects and modules must be called from the main application thread unless a method or module explicitly documents thread-safe behavior.
- Worker threads may be used by internal systems, but public object lifetime, resource loading, resource sharing and rendering calls remain main-thread operations.
- Callbacks that are documented as running on worker threads must not directly mutate GDK objects unless the called API is documented as thread-safe.

### Best practices

- All managers and modules are accessed exclusively through Main::instance(), never instantiate them directly
- Always call Main::terminate() before application exit to ensure proper cleanup
- Create the Main instance early in your application's startup sequence
- Call GDK module APIs from the main application thread unless the API explicitly documents thread-safe behavior
- Use the fixed frame rate system for consistent game logic across different hardware

Note
  Main is designed as a singleton and uses explicit destruction. It is automatically created on the first call to Main::instance() (this creation process is not thread-safe). Once created, it remains accessible throughout the application's lifetime via Main::instance().
  Always call Main::terminate() before exiting the application. At this time, any resource still loaded will be released, avoiding resource leaks.

## Namespaces
namespace | CRM64Pro::CMem
| CMem: CRM64Pro Memory Manager.

## Classes
struct | CRM64Pro::Position
| Absolute coordinate or helper-relative position used by layout APIs. More...
class | CRM64Pro::Main
| CRM64Pro GDK Main class. More...

## Enumerations
enum | CRM64Pro::eEventType : Uint32 { CRM64Pro::ET_C64 = 0xEC64 , CRM64Pro::ET_GUI_INTERNAL = 0xCFED }
| Custom SDL event types used by CRM64Pro. More...
enum | CRM64Pro::eEventCode : Sint32 { CRM64Pro::EC_LOGIC = 1 , CRM64Pro::EC_RENDER , CRM64Pro::EC_WIDGET_ACTION , CRM64Pro::EC_WIDGET_MOUSEHOVER , CRM64Pro::EC_WIDGET_LOSTFOCUS , CRM64Pro::EC_WIDGET_SELECTIONCHANGED , CRM64Pro::EC_WIDGET_VALUECHANGED , CRM64Pro::EC_WIDGET_TOGGLED , CRM64Pro::EC_WIDGET_VALUECOMMITTED }
| Event codes delivered via user.code when event.type is ET_C64. One code is delivered per event; values are not bitmask flags. More...
enum | CRM64Pro::eGeneralStatus : Sint32 { CRM64Pro::GS_DISABLED = 0 , CRM64Pro::GS_ENABLED = 1 , CRM64Pro::GS_PAUSED = 2 , CRM64Pro::GS_HIDDEN = 5 , CRM64Pro::GS_SHOWN = 9 , CRM64Pro::GS_END = 16 , CRM64Pro::GS_HIDING = 1024 , CRM64Pro::GS_SHOWING = 2048 }
enum | CRM64Pro::ePlaybackStatus : Sint32 { CRM64Pro::PS_STOPPED = 0 , CRM64Pro::PS_PLAYING = 1 , CRM64Pro::PS_PAUSED = 2 , CRM64Pro::PS_FINISHED = 3 }
| Playback status for audio and video objects. More...
enum | CRM64Pro::eErrorCode : Sint32 { CRM64Pro::C64_ERR_INTER = -256 , CRM64Pro::C64_ERR_PARAM = -512 , CRM64Pro::C64_ERR_FILOP = -768 , CRM64Pro::C64_ERR_FILWR = -1024 , CRM64Pro::C64_ERR_FILRE = -1280 , CRM64Pro::C64_ERR_ALLOC = -1536 , CRM64Pro::C64_ERR_OBJNF = -1792 , CRM64Pro::C64_ERR_STATE = -2048 , CRM64Pro::C64_ERR_UNSUP = -2304 , CRM64Pro::C64_ERR_LIMIT = -2560 , CRM64Pro::C64_ERR_DENIED = -2816 }
| Base error code families used by status-returning methods. More...
enum | CRM64Pro::ePositionHelper : Sint32 { CRM64Pro::PH_NONE = 0 , CRM64Pro::PH_SIZE = 0x60000000 , CRM64Pro::PH_CENTER = 0x61000000 , CRM64Pro::PH_TOP = 0x62000000 , CRM64Pro::PH_BOTTOM = 0x63000000 , CRM64Pro::PH_LEFT = 0x65000000 , CRM64Pro::PH_RIGHT = 0x66000000 , CRM64Pro::PH_KEEP = 0x6F000000 }
| Position helpers used by Cursors, Sprites, Fonts, GUI Widgets and Scene. One helper must be selected; values are not bitmask flags. More...

## Functions
static Main & | CRM64Pro::Main::instance ()
| Access the Main singleton.
static void | CRM64Pro::Main::terminate ()
| Main explicit destructor.
bool | CRM64Pro::Main::info (Sint32 iMode=0) override
| Request Main module information.
static bool | CRM64Pro::Main::isInit ()
| Check if the GDK is initialized.
const string & | CRM64Pro::Main::getCopyright () const
| Get copyright string.
void | CRM64Pro::Main::printVersion ()
| Print version and build date to the default log.
const string & | CRM64Pro::Main::getVersion () const
| Get version string.
bool | CRM64Pro::Main::requireVersion (Uint8 iMajor, Uint8 iMinor)
| Check if the GDK version is compatible with the given one.
bool | CRM64Pro::Main::intro (Sint32 idScreen=0)
| Show the MegaStorm and CRM64Pro introduction.
Sint32 | CRM64Pro::Main::update (SDL_Event *evUser=nullptr)
| Manage the GDK update cycle with a fixed virtual logic frame rate.
float | CRM64Pro::Main::getInterpolationFactor () const
| Get the current render interpolation factor.
float | CRM64Pro::Main::getDeltaTime () const
| Get the last frame's high-precision delta time.
float | CRM64Pro::Main::getLogicDeltaTime () const
| Get the delta time that must be consumed by the current logic step.
bool | CRM64Pro::Main::getKeyState (SDL_Keycode keycode) const
| Get the current state of a key.
const char * | CRM64Pro::Main::getKeyName (SDL_Keycode keycode) const
| Get a human-readable name for a key.
Sint32 | CRM64Pro::Main::getKeyboardFocus () const
| Get the screen that has keyboard focus.
ConfigMgr & | CRM64Pro::Main::configMgr ()
| Get reference to Config Manager.
Tool & | CRM64Pro::Main::tool ()
| Get reference to Tool module.
LogMgr & | CRM64Pro::Main::logMgr ()
| Get reference to Log Manager.
Timer & | CRM64Pro::Main::timer ()
| Get reference to Timer module.
ArchiveMgr & | CRM64Pro::Main::archiveMgr ()
| Get reference to Archive Manager.
XMLMgr & | CRM64Pro::Main::xmlMgr ()
| Get reference to XML Manager.
AudioTrackMgr & | CRM64Pro::Main::audioTrackMgr ()
| Get reference to Audio Track Manager.
ImageMgr & | CRM64Pro::Main::imageMgr ()
| Get reference to Image Manager.
CursorMgr & | CRM64Pro::Main::cursorMgr ()
| Get reference to Cursor Manager.
TileMgr & | CRM64Pro::Main::tileMgr ()
| Get reference to Tile Manager.
SpriteMgr & | CRM64Pro::Main::spriteMgr ()
| Get reference to Sprite Manager.
FontMgr & | CRM64Pro::Main::fontMgr ()
| Get reference to Font Manager.
GFX & | CRM64Pro::Main::gfx ()
| Get reference to GFX module.
Physics & | CRM64Pro::Main::physics ()
| Get reference to Physics module.
VideoMgr & | CRM64Pro::Main::videoMgr ()
| Get reference to Video Manager.
ParticleMgr & | CRM64Pro::Main::particleMgr ()
| Get reference to Particle Manager.
GUIMgr & | CRM64Pro::Main::guiMgr ()
| Get reference to GUI Manager.
SceneMgr & | CRM64Pro::Main::sceneMgr ()
| Get reference to Scene Manager.
NetTCP & | CRM64Pro::Main::netTCP ()
| Get reference to NetTCP module.

## Enumeration Type Documentation

## ◆ eEventType

enum CRM64Pro::eEventType : Uint32

Custom SDL event types used by CRM64Pro.

Enumerator
ET_C64 | CRM64Pro GDK internal events.
ET_GUI_INTERNAL | GUI focus system internal event.

## ◆ eEventCode

enum CRM64Pro::eEventCode : Sint32

Event codes delivered via user.code when event.type is ET_C64. One code is delivered per event; values are not bitmask flags.

Enumerator
EC_LOGIC | A logic frame occurred.
EC_RENDER | A render frame occurred.
EC_WIDGET_ACTION | A GUI button or command-style widget triggered an action.
EC_WIDGET_MOUSEHOVER | The mouse pointer is over a GUI widget.
EC_WIDGET_LOSTFOCUS | The GUI widget lost focus.
EC_WIDGET_SELECTIONCHANGED | A GUI widget selection changed.
EC_WIDGET_VALUECHANGED | A GUI widget numeric value changed.
EC_WIDGET_TOGGLED | A GUI checkbox toggled.
EC_WIDGET_VALUECOMMITTED | A GUI edit value was committed.

## ◆ eGeneralStatus

enum CRM64Pro::eGeneralStatus : Sint32

General status. One value must be returned; values are not bitmask flags.

Enumerator
GS_DISABLED | General status: disabled.
GS_ENABLED | General status: enabled.
GS_PAUSED | General status: paused.
GS_HIDDEN | General status: enabled but hidden.
GS_SHOWN | General status: enabled and shown.
GS_END | General status: end.
GS_HIDING | General status: hiding (fading effects).
GS_SHOWING | General status: showing (fading effects).

## ◆ ePlaybackStatus

enum CRM64Pro::ePlaybackStatus : Sint32

Playback status for audio and video objects.

Enumerator
PS_STOPPED | Playback is stopped or no playback instance is active.
PS_PLAYING | Playback is active.
PS_PAUSED | Playback is paused.
PS_FINISHED | Playback reached the end.

## ◆ eErrorCode

enum CRM64Pro::eErrorCode : Sint32

Base error code families used by status-returning methods.

Enumerator
C64_ERR_INTER | Internal error.
C64_ERR_PARAM | Invalid parameter.
C64_ERR_FILOP | File could not be opened or created.
C64_ERR_FILWR | File could not be written.
C64_ERR_FILRE | File could not be read.
C64_ERR_ALLOC | Memory could not be allocated.
C64_ERR_OBJNF | Object was not found.
C64_ERR_STATE | Object or module state does not allow the requested operation.
C64_ERR_UNSUP | Feature, format, codec, or operation is not supported.
C64_ERR_LIMIT | Capacity, range, or resource limit was reached.
C64_ERR_DENIED | Operation was denied by permissions, security policy, key state, or read-only state.

## ◆ ePositionHelper

enum CRM64Pro::ePositionHelper : Sint32

Position helpers used by Cursors, Sprites, Fonts, GUI Widgets and Scene. One helper must be selected; values are not bitmask flags.

Enumerator
PH_NONE | No position helper, absolute positioning.
PH_SIZE | Cursor::setHotSpot(): set hotspot to cursor_size. Sprite::setAnimHotSpot(): set hotspot to frame_size.
PH_CENTER | Cursor::setHotSpot(): set hotspot to cursor_size/2. Sprite::setAnimHotSpot(): set hotspot to frame_size/2. Widget/Font: center with optional offset. Scene: center relative to map bounds.
PH_TOP | Widget/Font: top with optional offset. Scene: align to map top/begin (0.0). Valid for Y axis.
PH_BOTTOM | Widget/Font: bottom with optional offset. Scene: align to map bottom/end (MapHeight - ViewportHeight). Valid for Y axis.
PH_LEFT | Widget/Font: left with optional offset. Scene: align to map left/begin (0.0). Valid for X axis.
PH_RIGHT | Widget/Font: right with optional offset. Scene: align to map right/end (MapWidth - ViewportWidth). Valid for X axis.
PH_KEEP | Scene: Keep the current value (ignore the new one).

## Function Documentation

## ◆ instance()

Main & CRM64Pro::Main::instance | ( |  | ) |
| static

Access the Main singleton.

On first call this performs:

- SDL event system initialization
- Creation of all modules and managers
- Creation of the default log object (must be initialized before use)
- Creation of the default screen, ready to enable
  Returns
    Reference to the Main singleton (only one instance exists).
  Note
    Creation is not thread-safe; call from the main thread before using other modules. Main uses explicit destruction so Main::terminate() must be called before application exit.

## ◆ terminate()

void CRM64Pro::Main::terminate | ( |  | ) |
| static

Main explicit destructor.

Shuts down SDL systems and GDK components. Call before exiting the application to release Main singleton resources.

## ◆ info()

bool CRM64Pro::Main::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Main module information.

Logs Main information using the default log.

Parameters

  iMode | Reserved for future use. Pass 0.

Returns
  true on success, or false on failure.

## ◆ isInit()

bool CRM64Pro::Main::isInit | ( |  | ) |
| static

Check if the GDK is initialized.

Returns
  false if the GDK is not initialized, true if it is.

## ◆ getCopyright()

const string & CRM64Pro::Main::getCopyright | ( |  | ) | const

Get copyright string.

Returns
  string with the copyright statement.

## ◆ printVersion()

void CRM64Pro::Main::printVersion | ( |  | ) |

Print version and build date to the default log.

Writes the version information; no return value.

## ◆ getVersion()

const string & CRM64Pro::Main::getVersion | ( |  | ) | const

Get version string.

Returns
  string with the current version.

## ◆ requireVersion()

bool CRM64Pro::Main::requireVersion | ( | Uint8 | iMajor,
|  | Uint8 | iMinor )

Check if the GDK version is compatible with the given one.

Parameters

  iMajor | Major version.
  iMinor | Minor version.

Returns
  true if compatible, false otherwise.

## ◆ intro()

bool CRM64Pro::Main::intro | ( | Sint32 | idScreen = 0 | ) |

Show the MegaStorm and CRM64Pro introduction.

Parameters

  idScreen | valid screen handle; defaults to the primary screen.

Returns
  true on success, or false on failure.

Note
  The screen must be initialized and shown. Audio is optional but recommended.

## ◆ update()

Sint32 CRM64Pro::Main::update | ( | SDL_Event * | evUser = nullptr | ) |

Manage the GDK update cycle with a fixed virtual logic frame rate.

This method is the heart of the engine's timing system. It replaces standard SDL_PollEvent() and implements a fixed virtual logic frame rate (LFR) with a high-resolution accumulator (nanoseconds). The system uses SDL_GetPerformanceCounter() to provide zero-drift timing and deterministic simulation steps. It manages:

- Input processing (polling and internal GUI/Console dispatching).
- Logic scheduling (ensuring constant simulation speed regardless of frame rate).
  - Render scheduling (throttling or unlocking rendering based on RFR).
  - Interpolation state calculation for smooth sub-pixel rendering.

Parameters

  evUser | Optional SDL event output pointer. If nullptr, an internal SDL event is used and event details are not returned to the caller. If not nullptr, it receives the next pending event. When evUser->type is ::ET_C64, evUser->user.code contains one of the ::eEventCode values.

Returns
  Control code: 0 when a logic step should be executed by the user, 1 when the loop should continue, or SDL_EVENT_QUIT when the application should close.

See also
  getLogicDeltaTime(), getInterpolationFactor(), getDeltaTime(), Game Loop Design

## ◆ getInterpolationFactor()

float CRM64Pro::Main::getInterpolationFactor | ( |  | ) | const

Get the current render interpolation factor.

Calculates the fractional progress between the last consumed logic frame and the next logic frame. This value ranges from [0.0, 1.0) while a fixed logic frame rate is enabled, and 0.0 when logic is variable-step. It is intended for render-only interpolation of visual state, such as Scene smooth scrolling and Sprite interpolated positions.

Note
  Using this value to interpolate between 'previous_position' and 'current_position' during rendering eliminates visual stutter on monitors with refresh rates different from the LFR. Do not use this value to advance logic.

Returns
  Interpolation factor in the [0.0, 1.0) range.

## ◆ getDeltaTime()

float CRM64Pro::Main::getDeltaTime | ( |  | ) | const

Get the last frame's high-precision delta time.

Provides the actual elapsed wall-clock time between the previous and current engine frame in seconds. The value is calculated using nanosecond-precision performance counters and is clamped to a maximum of 0.25s to prevent "spiral of death" catch-up loops after system lags.

Note
  In fixed logic mode this is not the amount of time consumed by a logic step. Use getLogicDeltaTime() for logic updates.

Returns
  The time in seconds elapsed since the last frame (e.g., 0.01666 for 60fps).

## ◆ getLogicDeltaTime()

float CRM64Pro::Main::getLogicDeltaTime | ( |  | ) | const

Get the delta time that must be consumed by the current logic step.

Returns the canonical logic-step delta in seconds. When a fixed logic frame rate (LFR) is enabled, this returns exactly 1.0 / LFR for every logic update. When LFR is disabled, logic is variable-step and this returns getDeltaTime().

Note
  Use this value for simulation, Scene updates, Video playback advancement, particles, AI, and other logic systems. Use getInterpolationFactor() only while rendering, and getDeltaTime() only when actual wall-clock frame time is required.

Returns
  Logic update delta time in seconds.

## ◆ getKeyState()

bool CRM64Pro::Main::getKeyState | ( | SDL_Keycode | keycode | ) | const

Get the current state of a key.

Uses the SDL keycode representation (layout-independent, character-dependent).

Parameters

  keycode | SDL keycode to check.

Returns
  true if the key is pressed, false otherwise.

## ◆ getKeyName()

const char * CRM64Pro::Main::getKeyName | ( | SDL_Keycode | keycode | ) | const

Get a human-readable name for a key.

Parameters

  keycode | SDL_Keycode key to get its human-readable name.

Returns
  Borrowed pointer to a character string valid until the next call, or an empty string if none exists.

Note
  The returned pointer must not be deleted or stored long-term.

## ◆ getKeyboardFocus()

Sint32 CRM64Pro::Main::getKeyboardFocus | ( |  | ) | const

Get the screen that has keyboard focus.

Returns
  Greater than 0 on success (the Screen id), or a negative error code on failure.

Note
  Use CursorMgr::getFocus() to obtain mouse focus.

## ◆ configMgr()

ConfigMgr & CRM64Pro::Main::configMgr | ( |  | ) |

Get reference to Config Manager.

Returns
  Reference to the Config Manager.

## ◆ tool()

Tool & CRM64Pro::Main::tool | ( |  | ) |

Get reference to Tool module.

Returns
  Reference to the Tool module.

## ◆ logMgr()

LogMgr & CRM64Pro::Main::logMgr | ( |  | ) |

Get reference to Log Manager.

Returns
  Reference to the Log Manager.

## ◆ timer()

Timer & CRM64Pro::Main::timer | ( |  | ) |

Get reference to Timer module.

Returns
  Reference to the Timer module.

## ◆ archiveMgr()

ArchiveMgr & CRM64Pro::Main::archiveMgr | ( |  | ) |

Get reference to Archive Manager.

Returns
  Reference to the Archive Manager.

## ◆ xmlMgr()

XMLMgr & CRM64Pro::Main::xmlMgr | ( |  | ) |

Get reference to XML Manager.

Returns
  Reference to the XML Manager.

## ◆ audioTrackMgr()

AudioTrackMgr & CRM64Pro::Main::audioTrackMgr | ( |  | ) |

Get reference to Audio Track Manager.

Returns
  Reference to the Audio Track Manager.

## ◆ imageMgr()

ImageMgr & CRM64Pro::Main::imageMgr | ( |  | ) |

Get reference to Image Manager.

Returns
  Reference to the Image Manager.

## ◆ cursorMgr()

CursorMgr & CRM64Pro::Main::cursorMgr | ( |  | ) |

Get reference to Cursor Manager.

Returns
  Reference to the Cursor Manager.

## ◆ tileMgr()

TileMgr & CRM64Pro::Main::tileMgr | ( |  | ) |

Get reference to Tile Manager.

Returns
  Reference to the Tile Manager.

## ◆ spriteMgr()

SpriteMgr & CRM64Pro::Main::spriteMgr | ( |  | ) |

Get reference to Sprite Manager.

Returns
  Reference to the Sprite Manager.

## ◆ fontMgr()

FontMgr & CRM64Pro::Main::fontMgr | ( |  | ) |

Get reference to Font Manager.

Returns
  Reference to the Font Manager.

## ◆ gfx()

GFX & CRM64Pro::Main::gfx | ( |  | ) |

Get reference to GFX module.

Returns
  Reference to the GFX module.

## ◆ physics()

Physics & CRM64Pro::Main::physics | ( |  | ) |

Get reference to Physics module.

Returns
  Reference to the Physics module.

## ◆ videoMgr()

VideoMgr & CRM64Pro::Main::videoMgr | ( |  | ) |

Get reference to Video Manager.

Returns
  Reference to the Video Manager.

## ◆ particleMgr()

ParticleMgr & CRM64Pro::Main::particleMgr | ( |  | ) |

Get reference to Particle Manager.

Returns
  Reference to the Particle Manager.

## ◆ guiMgr()

GUIMgr & CRM64Pro::Main::guiMgr | ( |  | ) |

Get reference to GUI Manager.

Returns
  Reference to the GUI Manager.

## ◆ sceneMgr()

SceneMgr & CRM64Pro::Main::sceneMgr | ( |  | ) |

Get reference to Scene Manager.

Returns
  Reference to the Scene Manager.

## ◆ netTCP()

NetTCP & CRM64Pro::Main::netTCP | ( |  | ) |

Get reference to NetTCP module.

Returns
  Reference to the NetTCP module.