Detailed Description

v2.00 (23 June 2023)
The Main module manages and provides access to the rest of modules.

The CRM64Pro::Main represents a starting point for the client application and also manages some important tasks:

System initialization and shutdown of the CRM64Pro.
Events and updating system.
Fixed virtual logic frame rate with interpolation.
Keyboard input system.
DRTS system.

Using this module, the application can gain access to the rest of modules:

There are two kinds of interfaces:

Standard: simple interface with a few methods that could or not be related.
Advanced: complex interface with several methods..

Regarding managers, there are three categorized types based on how they handle its objects:

Standard: creating or loading objects will work or fail but only one object with a specific name can be created or loaded.
Advanced - "Sharing": similar to standard but with advanced features. Loading new objects can share a previously created or loaded objects based on its name.
Advanced - "Cloning": similar to standard but with advanced features. Objects can be "cloned" sharing base features but can independently modify others. Loading new objects that are already created or loaded (based on the name), will automatically create a "cloned" object.

Acts as a hub from which all other interfaces can be reached. Main is designed as a singleton and only one instance will exists.
It is automatically created the first time Main::Instance() is called. This creation process is not thread-safe.
Once the instance is created, it is accessible throughout the life of client application using Main::Instance().
Main singleton is using explicit destruction so do not forget to call Main::Terminate() before exiting from the application.

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

Classes
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_END = 0x60000000 , CRM64Pro::PH_CENTER = 0x61000000 , CRM64Pro::PH_CENTERD = 0x71000000 , CRM64Pro::PH_TOP = 0x62000000 , CRM64Pro::PH_TOPD = 0x72000000 , CRM64Pro::PH_BOTTOM = 0x63000000 , CRM64Pro::PH_BOTTOMD = 0x73000000 , CRM64Pro::PH_LEFT = 0x65000000 , CRM64Pro::PH_LEFTD = 0x75000000 , CRM64Pro::PH_RIGHT = 0x66000000 , CRM64Pro::PH_RIGHTD = 0x76000000 }
	Position helpers used by Cursor, Sprite, Font and GUI Widgets. More...

Functions
static Main &	CRM64Pro::Main::Instance ()
	Creates the Main instance.

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 compiled date to our default log object.

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::update (SDL_Event *evUser=nullptr)
	Main application update governor.

float	CRM64Pro::Main::getLogicTime ()
	Get logic time.

Sint32	CRM64Pro::Main::getKeyState (SDL_Keycode keycode)
	Get the 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 id which currently has keyboard focus.

ConfigMgr &	CRM64Pro::Main::IConfigMgr ()
	Get the reference to the Config Manager.

Tool &	CRM64Pro::Main::ITool ()
	Get the reference to the Tool Interface.

LogMgr &	CRM64Pro::Main::ILogMgr ()
	Get the reference to the Log Manager.

Timer &	CRM64Pro::Main::ITimer ()
	Get the reference to the Timer Interface.

ArchiveMgr &	CRM64Pro::Main::IArchiveMgr ()
	Get the reference to the Archive Manager.

XMLMgr &	CRM64Pro::Main::IXMLMgr ()
	Get the reference to the XML Manager.

MusicMgr &	CRM64Pro::Main::IMusicMgr ()
	Get the reference to the Music Manager.

SoundMgr &	CRM64Pro::Main::ISoundMgr ()
	Get the reference to the Sound Manager.

ImageMgr &	CRM64Pro::Main::IImageMgr ()
	Get the reference to the Image Manager.

CursorMgr &	CRM64Pro::Main::ICursorMgr ()
	Get the reference to the Cursor Manager.

TileMgr &	CRM64Pro::Main::ITileMgr ()
	Get the reference to the Tile Manager.

SpriteMgr &	CRM64Pro::Main::ISpriteMgr ()
	Get the reference to the Sprite Manager.

FontMgr &	CRM64Pro::Main::IFontMgr ()
	Get the reference to the Font Manager.

GFX &	CRM64Pro::Main::IGFX ()
	Get the reference to the GFX Interface.

GUIMgr &	CRM64Pro::Main::IGUIMgr ()
	Get the reference to the GUI Manager.

TileEngineMgr &	CRM64Pro::Main::ITileEngineMgr ()
	Get the reference to the TileEngine Manager.

NetTCP &	CRM64Pro::Main::INetTCP ()
	Get the reference to the NetTCP Interface.

Macro Definition Documentation

◆ C64_EVENT

#define C64_EVENT 0xEC64

Event type returned by Main::update() setting one of available codes.

◆ C64_EVENT_LOGIC

#define C64_EVENT_LOGIC 1

event.user.code returned by Main::update() with C64_EVENT event type. A logic frame occurred.

◆ C64_EVENT_RENDER

#define C64_EVENT_RENDER 2

event.user.code returned by Main::update() with C64_EVENT event type. A render frame occurred.

◆ C64_EVENT_WIDGET

#define C64_EVENT_WIDGET 4

event.user.code returned by Main::update() with C64_EVENT event type. A GUI Widget triggered an WS_ACTION event.

◆ C64_EVENT_WIDGET_MOUSEOVER

#define C64_EVENT_WIDGET_MOUSEOVER 8

event.user.code returned by Main::update() with C64_EVENT event type. The mouse pointer is over a GUI Widget.

◆ C64_EVENT_WIDGET_LOSTFOCUS

#define C64_EVENT_WIDGET_LOSTFOCUS 16

event.user.code returned by Main::update() with C64_EVENT event type. The GUI Widget lost the 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/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 Cursor, Sprite, Font and GUI Widgets.

Enumerator
PH_END	Used with Cursor::setHotSpot() to set as hotspot the cursor_size. Used with Sprite::setAnimHotSpot() to set as hotspot the frame_size.
PH_CENTER	Used with Cursor::setHotSpot() to set as hotspot the cursor_size/2. Used with Sprite::setAnimHotSpot() to set as hotspot the frame_size/2. Widget and Font relative position: center with optional increment.
PH_CENTERD	Widget and Font relative position: center with optional decrement.
PH_TOP	Widget and Font relative position: top with optional increment. Valid for Y axis.
PH_TOPD	Widget and Font relative position: top with optional decrement. Valid for Y axis.
PH_BOTTOM	Widget and Font relative position: bottom with optional increment. Valid for Y axis.
PH_BOTTOMD	Widget and Font relative position: bottom with optional decrement. Valid for Y axis.
PH_LEFT	Widget and Font relative position: left with optional increment. Valid for X axis.
PH_LEFTD	Widget and Font relative position: left with optional decrement. Valid for X axis.
PH_RIGHT	Widget and Font relative position: right with optional increment. Valid for X axis.
PH_RIGHTD	Widget and Font relative position: right with optional decrement. Valid for X axis.

Function Documentation

◆ Instance()

Main & CRM64Pro::Main::Instance ( )

static

Creates the Main instance.

Main automatically performs these tasks:

initialize SDL event system
creates all interfaces and managers
create the default log object which must be initialized in order to be enabled
create the default screen ready for being enabled

Returns: A reference to the Main instance (only one is created)

Note: Main is a singleton and it is created the first time a reference is requested.
The creation process is not thread-safe but it does not matter as it should be called first from the main thread.
Main uses explicit destruction so a call to Main::Terminate() must be done before exiting from the client application.

◆ Terminate()

void CRM64Pro::Main::Terminate ( )

static

Main explicit destructor.

Close all SDL systems and GDK components.
Must be called before exiting from the client application to take care of removing Main singleton resources.

◆ info()

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

Request Main Interface information.

For displaying the information, it uses 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 GDK is not initalized or 1 if it is.

◆ getCopyright()

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

Get copyright string.

Returns: std:string with the copyright string.

◆ printVersion()

void CRM64Pro::Main::printVersion ( )

Print version and compiled date to our default log object.

Does not return any value, just print the version.

◆ getVersion()

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

Get version string.

Returns: std:string with the version string.

◆ 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 GDK version is less than requested or 0 if GDK version is equal or greater than requested.

◆ update()

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

Main application update governor.

This method is very important and replaces some SDL functions as SDL_PollEvent() or SDL_RenderPresent() and update other internal system as GUI or Timer.
It also provides an important feature of the GDK, the fixed virtual logic frame rate with interpolation feature.
As there are some ways to use it which target different application behaviours, it is recommended to read and understand this extended information page.

The workflow for every call to this method follow below priority steps:

(P1) When the evUser parameter is used, try to get a pending event, store it on evUser and return 1. If it is not used(nullptr) or it is but there isnt any pending event, go to next step.
Note that SDL_EVENT_KEY_DOWN and SDL_EVENT_KEY_UP events are filtered out when a TextBox Widget has the focus.
(P2) Check if a Logic Frame must be executed for updating the keyboard, mouse and GUI systems. The Logic Frame execution occurs always when no Logic Frame Rate is set or
if it is set using Timer::setRate() and must be executed now. In this case, it will return 0, otherwise, go to next step.
(P3) Check if a Render Frame must be executed for calling screen render callbacks, SDL_RenderPresent() of all visible screens and render the GUI. The Render Frame execution occurs always when no Render Frame Rate is set or
if it is set using Timer::setRate() and must be executed now. Go to next step.
(P4) Update the Timer system and delay (give back the execution control to the OS) in case ConfigMgr::iMTFriendly is set.

Parameters

evUser SDL_Event pointer, by default is nullptr.

Returns: 1 when there is a pending event on the SDL event queue. 0 when there are none available.

◆ getLogicTime()

float CRM64Pro::Main::getLogicTime ( )

Get logic time.

Returns: total logic time.

Note: This method is used internally for getting use of the fixed virtual logic frame rate with interpolation.

◆ getKeyState()

Sint32 CRM64Pro::Main::getKeyState ( SDL_Keycode keycode )

Get the state of a key.

From the two different types of values to represent keys on the SDL system, we are using the keycode approach.
Keycode type is character-dependent and keyboard layout-independent.

Parameters

keycode SDL_Keycode key to get its state.

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

◆ 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: A pointer to a character string that stays valid at least until the next call to this function or an empty character string if there is not a name.

◆ getKeyboardFocus()

Sint32 CRM64Pro::Main::getKeyboardFocus ( )

Get the Screen id which currently has keyboard focus.

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

Note: For getting the mouse focus you can use CursorMgr::getFocus() method.

◆ IConfigMgr()

ConfigMgr & CRM64Pro::Main::IConfigMgr ( )

Get the reference to the Config Manager.

Returns: a reference to the Config Manager.

◆ ITool()

Tool & CRM64Pro::Main::ITool ( )

Get the reference to the Tool Interface.

Returns: a reference to the Tool Interface.

◆ ILogMgr()

LogMgr & CRM64Pro::Main::ILogMgr ( )

Get the reference to the Log Manager.

Returns: a reference to the Log Manager.

◆ ITimer()

Timer & CRM64Pro::Main::ITimer ( )

Get the reference to the Timer Interface.

Returns: a reference to the Timer Interface.

◆ IArchiveMgr()

ArchiveMgr & CRM64Pro::Main::IArchiveMgr ( )

Get the reference to the Archive Manager.

Returns: a reference to the Archive Manager.

◆ IXMLMgr()

XMLMgr & CRM64Pro::Main::IXMLMgr ( )

Get the reference to the XML Manager.

Returns: a reference to the XML Manager.

◆ IMusicMgr()

MusicMgr & CRM64Pro::Main::IMusicMgr ( )

Get the reference to the Music Manager.

Returns: a reference to the Music Manager.

◆ ISoundMgr()

SoundMgr & CRM64Pro::Main::ISoundMgr ( )

Get the reference to the Sound Manager.

Returns: a reference to the Sound Manager.

◆ IImageMgr()

ImageMgr & CRM64Pro::Main::IImageMgr ( )

Get the reference to the Image Manager.

Returns: a reference to the Image Manager.

◆ ICursorMgr()

CursorMgr & CRM64Pro::Main::ICursorMgr ( )

Get the reference to the Cursor Manager.

Returns: a reference to the Cursor Manager.

◆ ITileMgr()

TileMgr & CRM64Pro::Main::ITileMgr ( )

Get the reference to the Tile Manager.

Returns: a reference to the Tile Manager.

◆ ISpriteMgr()

SpriteMgr & CRM64Pro::Main::ISpriteMgr ( )

Get the reference to the Sprite Manager.

Returns: a reference to the Sprite Manager.

◆ IFontMgr()

FontMgr & CRM64Pro::Main::IFontMgr ( )

Get the reference to the Font Manager.

Returns: a reference to the Font Manager.

◆ IGFX()

GFX & CRM64Pro::Main::IGFX ( )

Get the reference to the GFX Interface.

Returns: a reference to the GFX Interface.

◆ IGUIMgr()

GUIMgr & CRM64Pro::Main::IGUIMgr ( )

Get the reference to the GUI Manager.

Returns: a reference to the GUI Manager.

◆ ITileEngineMgr()

TileEngineMgr & CRM64Pro::Main::ITileEngineMgr ( )

Get the reference to the TileEngine Manager.

Returns: a reference to the TileEngine Manager.

◆ INetTCP()

NetTCP & CRM64Pro::Main::INetTCP ( )

Get the reference to the NetTCP Interface.

Returns: a reference to the NetTCP Interface.

Detailed Description

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

◆ update()

◆ getLogicTime()

◆ getKeyState()

◆ getKeyName()

◆ getKeyboardFocus()

◆ IConfigMgr()

◆ ITool()

◆ ILogMgr()

◆ ITimer()

◆ IArchiveMgr()

◆ IXMLMgr()

◆ IMusicMgr()

◆ ISoundMgr()

◆ IImageMgr()

◆ ICursorMgr()

◆ ITileMgr()

◆ ISpriteMgr()

◆ IFontMgr()

◆ IGFX()

◆ IGUIMgr()

◆ ITileEngineMgr()

◆ INetTCP()