CRM64Pro GDK  v0.94
A free cross-platform game development kit built on top of SDL 2.0
Classes | Macros | Functions
Main

Classes

class  CRM64Pro::Main
 

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

Functions

static Main & CRM64Pro::Main::Instance ()
 
static void CRM64Pro::Main::Terminate ()
 
Sint32 CRM64Pro::Main::info (Sint32 iMode=0)
 
Sint32 CRM64Pro::Main::isInit ()
 
const string & CRM64Pro::Main::getCopyright ()
 
const string & CRM64Pro::Main::getVersion ()
 
Sint32 CRM64Pro::Main::requireVersion (Uint8 iMajor, Uint8 iMinor)
 
Sint32 CRM64Pro::Main::update (SDL_Event *evUser=nullptr)
 
float CRM64Pro::Main::getLogicTime ()
 
Sint32 CRM64Pro::Main::getKeyState (SDL_Keycode keycode)
 
const char * CRM64Pro::Main::getKeyName (SDL_Keycode keycode)
 
Sint32 CRM64Pro::Main::getKeyboardFocus ()
 

Detailed Description

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

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

CRM64Pro_Main.png


There are two kinds of interfaces:

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


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.

Macro Definition Documentation

#define C64_EVENT   0xEC64

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

#define C64_EVENT_LOGIC   1

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

#define C64_EVENT_RENDER   2

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

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

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

#define C64_EVENT_WIDGET_LOSTFOCUS   16

event.user.code returned by Main::update() with C64_EVENT event type. The GUI Widget lost the focus.

#define C64_STATUS_DISABLED   0

General Status: disabled.

#define C64_STATUS_ENABLED   1

General Status: enabled.

#define C64_STATUS_PAUSED   2

General Status: paused.

#define C64_STATUS_HIDDEN   5

General Status: enabled but hidden.

#define C64_STATUS_SHOWN   9

General Status: enabled and shown.

#define C64_ERR_INTER   0xFFFFFF00

Error code: Internal error.

#define C64_ERR_PARAM   0xFFFFFE00

Error code: Invalid parameter.

#define C64_ERR_FILOP   0xFFFFFD00

Error code: Could not open/create a file.

#define C64_ERR_FILWR   0xFFFFFC00

Error code: Could not write to a file.

#define C64_ERR_FILRE   0xFFFFFB00

Error code: Could not read from a file.

#define C64_ERR_ALLOC   0xFFFFFA00

Error code: Could not allocate memory.

#define C64_ERR_OBJNF   0xFFFFF900

Error code: Object not found.

Function Documentation

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

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

Request Main Interface information.

For displaying the information, it uses the default log.

Parameters
iModeunused for the time being.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::Main::isInit ( )

Check if the GDK is initialized.

Returns
0 GDK is not initalized or 1 if it is.
const string & CRM64Pro::Main::getCopyright ( )

Get copyright string.

Returns
std:string with the copyright string.
const string & CRM64Pro::Main::getVersion ( )

Get version string.

Returns
std:string with the version string.
Sint32 CRM64Pro::Main::requireVersion ( Uint8  iMajor,
Uint8  iMinor 
)

Check given version against GDK version.

Parameters
iMajorrequired major version.
iMinorrequired minor version.
Returns
-1 GDK version is less than requested or 0 if GDK version is equal or greater than requested.
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_KEYDOWN and SDL_KEYUP 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
evUserSDL_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.
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.
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
keycodeSDL_Keycode key to get its state.
Returns
0 when the key is not pressed, 1 if it is pressed or a negative error code on failure.
const char * CRM64Pro::Main::getKeyName ( SDL_Keycode  keycode)

Get a human-readable name for a key.

Parameters
keycodeSDL_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.
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.