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
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
	Position struct used by Font and GUI Widgets. 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.
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.

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

Description

Overview

Key features

Module access

Module types

Manager types

Return value conventions

Threading conventions

Best practices

Namespaces

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ eEventType

◆ eEventCode

◆ eGeneralStatus

◆ ePlaybackStatus

◆ eErrorCode

◆ ePositionHelper

Function Documentation

◆ instance()

◆ terminate()

◆ info()

◆ isInit()

◆ getCopyright()

◆ printVersion()

◆ getVersion()

◆ requireVersion()

◆ intro()

◆ update()

◆ getInterpolationFactor()

◆ getDeltaTime()

◆ getLogicDeltaTime()

◆ getKeyState()

◆ getKeyName()

◆ getKeyboardFocus()

◆ configMgr()

◆ tool()

◆ logMgr()

◆ timer()

◆ archiveMgr()

◆ xmlMgr()

◆ audioTrackMgr()

◆ imageMgr()

◆ cursorMgr()

◆ tileMgr()

◆ spriteMgr()

◆ fontMgr()

◆ gfx()

◆ physics()

◆ videoMgr()

◆ guiMgr()

◆ sceneMgr()

◆ netTCP()