Main

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.