Description

Central hub for CRM64Pro GDK initialization and module access [v25.12.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
Fixed virtual logic frame rate with interpolation (check here for more info)
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	TE Core • TE MapData
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_EVENT 0xEC64
#define	C64_EVENT_LOGIC 1
#define	C64_EVENT_RENDER 2
#define	C64_EVENT_WIDGET 4
#define	C64_EVENT_WIDGET_MOUSEOVER 8
#define	C64_EVENT_WIDGET_LOSTFOCUS 16
#define	C64_STATUS_DISABLED 0
#define	C64_STATUS_ENABLED 1
#define	C64_STATUS_PAUSED 2
#define	C64_STATUS_HIDDEN 5
#define	C64_STATUS_SHOWN 9
#define	C64_STATUS_END 16
#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::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 }
	Position helpers used by Cursors, Sprites, Fonts and GUI Widgets. More...

Functions
static Main &	CRM64Pro::Main::Instance ()
	Access the Main singleton.
static void	CRM64Pro::Main::Terminate ()
	Main explicit destructor.
Sint32	CRM64Pro::Main::info (Sint32 iMode=0)
	Request Main Interface information.
static Sint32	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.
Sint32	CRM64Pro::Main::requireVersion (Uint8 iMajor, Uint8 iMinor)
	Check given version against GDK version.
Sint32	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 ()
	Get total logic time.
Sint32	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 ()
	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.
GUIMgr &	CRM64Pro::Main::IGUIMgr ()
	Get reference to GUI Manager.
TileEngineMgr &	CRM64Pro::Main::ITileEngineMgr ()
	Get reference to TileEngine Manager.
NetTCP &	CRM64Pro::Main::INetTCP ()
	Get reference to NetTCP Interface.

Macro Definition Documentation

◆ C64_EVENT

#define C64_EVENT 0xEC64

Event type raised by Main::update() to deliver a CRM64Pro user event code.

◆ C64_EVENT_LOGIC

#define C64_EVENT_LOGIC 1

event.user.code set by Main::update() when event.type is C64_EVENT. A logic frame occurred.

◆ C64_EVENT_RENDER

#define C64_EVENT_RENDER 2

event.user.code set by Main::update() when event.type is C64_EVENT. A render frame occurred.

◆ C64_EVENT_WIDGET

#define C64_EVENT_WIDGET 4

event.user.code set by Main::update() when event.type is C64_EVENT. A GUI widget triggered a WS_ACTION event.

◆ C64_EVENT_WIDGET_MOUSEOVER

#define C64_EVENT_WIDGET_MOUSEOVER 8

event.user.code set by Main::update() when event.type is C64_EVENT. The mouse pointer is over a GUI widget.

◆ C64_EVENT_WIDGET_LOSTFOCUS

#define C64_EVENT_WIDGET_LOSTFOCUS 16

event.user.code set by Main::update() when event.type is C64_EVENT. The GUI widget lost focus.

◆ C64_STATUS_DISABLED

#define C64_STATUS_DISABLED 0

General status: disabled.

◆ C64_STATUS_ENABLED

#define C64_STATUS_ENABLED 1

General status: enabled.

◆ C64_STATUS_PAUSED

#define C64_STATUS_PAUSED 2

General status: paused.

◆ C64_STATUS_HIDDEN

#define C64_STATUS_HIDDEN 5

General status: enabled but hidden.

◆ C64_STATUS_SHOWN

#define C64_STATUS_SHOWN 9

General status: enabled and shown.

◆ C64_STATUS_END

#define C64_STATUS_END 16

General status: end.

◆ 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

◆ ePositionHelpers

enum CRM64Pro::ePositionHelpers

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

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 (use negative for decrement).
PH_TOP	Widget/Font: top with optional offset (use negative for decrement). Valid for Y axis.
PH_BOTTOM	Widget/Font: bottom with optional offset (use negative for decrement). Valid for Y axis.
PH_LEFT	Widget/Font: left with optional offset (use negative for decrement). Valid for X axis.
PH_RIGHT	Widget/Font: right with optional offset (use negative for decrement). Valid for X axis.

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

Sint32 CRM64Pro::Main::info ( Sint32 iMode = 0 )

Request Main Interface information.

Logs Main information using the default log.

Parameters

iMode unused for the time being.

Returns: 0 on success, or a negative error code on failure.

◆ isInit()

Sint32 CRM64Pro::Main::isInit ( )

static

Check if the GDK is initialized.

Returns: 0 if the GDK is not initialized, 1 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()

Sint32 CRM64Pro::Main::requireVersion	(	Uint8	iMajor,
		Uint8	iMinor )

Check given version against GDK version.

Parameters

iMajor	required major version.
iMinor	required minor version.

Returns: -1 if the GDK version is lower than requested, or 0 if it matches or exceeds the requirement.

◆ intro()

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

Show the MegaStorm and CRM64Pro introduction.

Parameters

idScreen valid screen handle; defaults to the primary screen.

Returns: 0 on success, or a negative error code 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.

Replaces SDL_PollEvent() and SDL_RenderPresent(), while updating internal systems such as GUI and Timer. Provides the fixed virtual logic frame rate with interpolation.

Parameters

evUser event data pointer. If event.type is C64_EVENT, evUser.user.code contains the event code. If event.type is SDL_EVENT_GUI_WINDOW_CLOSE_REQUESTED, the user clicked to close the window.

Returns: Event type or SDL_EVENT_QUIT if the user requested to quit.

See also: Game Loop Design for details about the fixed virtual logic frame rate with interpolation.

◆ getLogicTime()

float CRM64Pro::Main::getLogicTime ( )

Get total logic time.

Returns: Total logic time.

Note: Used internally to support the fixed virtual logic frame rate with interpolation.

◆ getKeyState()

Sint32 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 key to check.

Returns: 1 if the key is pressed, or 0 if it is not.

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

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.

◆ IGUIMgr()

GUIMgr & CRM64Pro::Main::IGUIMgr ( )

Get reference to GUI Manager.

Returns: Reference to the GUI Manager.

◆ ITileEngineMgr()

TileEngineMgr & CRM64Pro::Main::ITileEngineMgr ( )

Get reference to TileEngine Manager.

Returns: Reference to the TileEngine Manager.

◆ INetTCP()

NetTCP & CRM64Pro::Main::INetTCP ( )

Get reference to NetTCP Interface.

Returns: Reference to the NetTCP Interface.

Description

Overview

Key features

Module access

Interface types

Manager types

Best practices

Namespaces

Classes

Macros

Enumerations

Functions

Macro Definition Documentation

◆ C64_EVENT

◆ C64_EVENT_LOGIC

◆ C64_EVENT_RENDER

◆ C64_EVENT_WIDGET

◆ C64_EVENT_WIDGET_MOUSEOVER

◆ C64_EVENT_WIDGET_LOSTFOCUS

◆ C64_STATUS_DISABLED

◆ C64_STATUS_ENABLED

◆ C64_STATUS_PAUSED

◆ C64_STATUS_HIDDEN

◆ C64_STATUS_SHOWN

◆ C64_STATUS_END

◆ C64_ERR_INTER

◆ C64_ERR_PARAM

◆ C64_ERR_FILOP

◆ C64_ERR_FILWR

◆ C64_ERR_FILRE

◆ C64_ERR_ALLOC

◆ C64_ERR_OBJNF

Enumeration Type Documentation

◆ ePositionHelpers

Function Documentation

◆ Instance()

◆ Terminate()

◆ info()

◆ isInit()

◆ getCopyright()

◆ printVersion()

◆ getVersion()

◆ requireVersion()

◆ intro()

◆ update()

◆ getLogicTime()

◆ getKeyState()

◆ getKeyName()

◆ getKeyboardFocus()

◆ IConfigMgr()

◆ ITool()

◆ ILogMgr()

◆ ITimer()

◆ IArchiveMgr()

◆ IXMLMgr()

◆ IAudioTrackMgr()

◆ IImageMgr()

◆ ICursorMgr()

◆ ITileMgr()

◆ ISpriteMgr()

◆ IFontMgr()

◆ IGFX()

◆ IGUIMgr()

◆ ITileEngineMgr()

◆ INetTCP()