| CRM64Pro GDK v0.15.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.02.0].

### 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
Interface | GUI • Widgets
Tile engine | Scene Core • Scene TileLayer
Network | TCP/IP

### Interface types

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

Standard | Simple interface with a few methods that may or may not be related
Advanced | Complex interface 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

### Best practices

- All managers and interfaces 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
- Avoid calling Main::Instance() from multiple threads during initial creation
- 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 from 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
| Position struct used by Font and GUI Widgets. More...
class | CRM64Pro::Main
| CRM64Pro GDK Main class. More...

## Macros
#define | C64_ERR_INTER 0xFFFFFF00
#define | C64_ERR_PARAM 0xFFFFFE00
#define | C64_ERR_FILOP 0xFFFFFD00
#define | C64_ERR_FILWR 0xFFFFFC00
#define | C64_ERR_FILRE 0xFFFFFB00
#define | C64_ERR_ALLOC 0xFFFFFA00
#define | C64_ERR_OBJNF 0xFFFFF900

## 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 = 2 , CRM64Pro::EC_WIDGET_ACTION = 4 , CRM64Pro::EC_WIDGET_MOUSEHOVER = 8 , CRM64Pro::EC_WIDGET_LOSTFOCUS = 16 }
| Event codes delivered via user.code when event.type is ET_C64. 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::ePositionHelpers { 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. 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 Interface information.
static bool | CRM64Pro::Main::isInit ()
| Check if the GDK is initialized.
const string & | CRM64Pro::Main::getCopyright ()
| Get copyright string.
void | CRM64Pro::Main::printVersion ()
| Print version and build date to the default log.
const string & | CRM64Pro::Main::getVersion ()
| 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::getLogicTime () const
| Get the current logic interpolation alpha.
float | CRM64Pro::Main::getDeltaTime () const
| Get the last frame's high-precision delta time.
bool | CRM64Pro::Main::getKeyState (SDL_Keycode keycode)
| Get the current state of a key.
const char * | CRM64Pro::Main::getKeyName (SDL_Keycode keycode)
| Get a human-readable name for a key.
Sint32 | CRM64Pro::Main::getKeyboardFocus () const
| Get the screen that has keyboard focus.
ConfigMgr & | CRM64Pro::Main::IConfigMgr ()
| Get reference to Config Manager.
Tool & | CRM64Pro::Main::ITool ()
| Get reference to Tool Interface.
LogMgr & | CRM64Pro::Main::ILogMgr ()
| Get reference to Log Manager.
Timer & | CRM64Pro::Main::ITimer ()
| Get reference to Timer Interface.
ArchiveMgr & | CRM64Pro::Main::IArchiveMgr ()
| Get reference to Archive Manager.
XMLMgr & | CRM64Pro::Main::IXMLMgr ()
| Get reference to XML Manager.
AudioTrackMgr & | CRM64Pro::Main::IAudioTrackMgr ()
| Get reference to Audio Track Manager.
ImageMgr & | CRM64Pro::Main::IImageMgr ()
| Get reference to Image Manager.
CursorMgr & | CRM64Pro::Main::ICursorMgr ()
| Get reference to Cursor Manager.
TileMgr & | CRM64Pro::Main::ITileMgr ()
| Get reference to Tile Manager.
SpriteMgr & | CRM64Pro::Main::ISpriteMgr ()
| Get reference to Sprite Manager.
FontMgr & | CRM64Pro::Main::IFontMgr ()
| Get reference to Font Manager.
GFX & | CRM64Pro::Main::IGFX ()
| Get reference to GFX Interface.
Physics & | CRM64Pro::Main::IPhysics ()
| Get reference to Physics Interface.
GUIMgr & | CRM64Pro::Main::IGUIMgr ()
| Get reference to GUI Manager.
SceneMgr & | CRM64Pro::Main::ISceneMgr ()
| Get reference to Scene Manager.
NetTCP & | CRM64Pro::Main::INetTCP ()
| Get reference to NetTCP Interface.

## Macro Definition Documentation

## ◆ C64_ERR_INTER

#define C64_ERR_INTER 0xFFFFFF00

Error code: internal error.

## ◆ C64_ERR_PARAM

#define C64_ERR_PARAM 0xFFFFFE00

Error code: invalid parameter.

## ◆ C64_ERR_FILOP

#define C64_ERR_FILOP 0xFFFFFD00

Error code: could not open or create a file.

## ◆ C64_ERR_FILWR

#define C64_ERR_FILWR 0xFFFFFC00

Error code: could not write to a file.

## ◆ C64_ERR_FILRE

#define C64_ERR_FILRE 0xFFFFFB00

Error code: could not read from a file.

## ◆ C64_ERR_ALLOC

#define C64_ERR_ALLOC 0xFFFFFA00

Error code: could not allocate memory.

## ◆ C64_ERR_OBJNF

#define C64_ERR_OBJNF 0xFFFFF900

Error code: object not found.

## 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.

Enumerator
EC_LOGIC | A logic frame occurred.
EC_RENDER | A render frame occurred.
EC_WIDGET_ACTION | A GUI widget triggered a WS_ACTION event.
EC_WIDGET_MOUSEHOVER | The mouse pointer is over a GUI widget.
EC_WIDGET_LOSTFOCUS | The GUI widget lost focus.

## ◆ eGeneralStatus

enum CRM64Pro::eGeneralStatus : Sint32

General status.

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).

## ◆ ePositionHelpers

enum CRM64Pro::ePositionHelpers

Position helpers used by Cursors, Sprites, Fonts, GUI Widgets and Scene.

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 interfaces 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 Interface information.

Logs Main information using the default log.

Parameters

  iMode | unused for the time being.

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 | ( |  | ) |

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 | ( |  | ) |

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 utilizes 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 | event data pointer. If event.type is ET_C64, evUser.user.code contains the event code (EC_LOGIC, EC_RENDER, etc).

Returns
  0 if a Logic Step should be executed by the user, 1 if the loop should continue (Input/Render handled), or SDL_EVENT_QUIT if the application should close.

See also
  getLogicTime(), getDeltaTime(), Game Loop Design

## ◆ getLogicTime()

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

Get the current logic interpolation alpha.

Calculates the fractional progress between the current and the next logic frame. This value ranges from [0.0, 1.0) and is essential for implementing smooth visual movement (interpolation) in rendering systems like the Scene.

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.

Returns
  Float value [0.0, 1.0) representing the interpolation alpha.

## ◆ getDeltaTime()

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

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

Provides the actual time elapsed between the previous and current 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.

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

## ◆ getKeyState()

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

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 | ) |

Get a human-readable name for a key.

Parameters

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

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

## ◆ getKeyboardFocus()

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

Get the screen that has keyboard focus.

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

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

## ◆ IConfigMgr()

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

Get reference to Config Manager.

Returns
  Reference to the Config Manager.

## ◆ ITool()

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

Get reference to Tool Interface.

Returns
  Reference to the Tool Interface.

## ◆ ILogMgr()

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

Get reference to Log Manager.

Returns
  Reference to the Log Manager.

## ◆ ITimer()

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

Get reference to Timer Interface.

Returns
  Reference to the Timer Interface.

## ◆ IArchiveMgr()

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

Get reference to Archive Manager.

Returns
  Reference to the Archive Manager.

## ◆ IXMLMgr()

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

Get reference to XML Manager.

Returns
  Reference to the XML Manager.

## ◆ IAudioTrackMgr()

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

Get reference to Audio Track Manager.

Returns
  Reference to the Audio Track Manager.

## ◆ IImageMgr()

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

Get reference to Image Manager.

Returns
  Reference to the Image Manager.

## ◆ ICursorMgr()

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

Get reference to Cursor Manager.

Returns
  Reference to the Cursor Manager.

## ◆ ITileMgr()

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

Get reference to Tile Manager.

Returns
  Reference to the Tile Manager.

## ◆ ISpriteMgr()

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

Get reference to Sprite Manager.

Returns
  Reference to the Sprite Manager.

## ◆ IFontMgr()

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

Get reference to Font Manager.

Returns
  Reference to the Font Manager.

## ◆ IGFX()

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

Get reference to GFX Interface.

Returns
  Reference to the GFX Interface.

## ◆ IPhysics()

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

Get reference to Physics Interface.

Returns
  Reference to the Physics Interface.

## ◆ IGUIMgr()

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

Get reference to GUI Manager.

Returns
  Reference to the GUI Manager.

## ◆ ISceneMgr()

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

Get reference to Scene Manager.

Returns
  Reference to the Scene Manager.

## ◆ INetTCP()

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

Get reference to NetTCP Interface.

Returns
  Reference to the NetTCP Interface.