CRM64Pro GDK v0.980
A free cross-platform game development kit built on top of SDL 2.0
Loading...
Searching...
No Matches

Detailed Description

v3.00 (29 April 2023)
The Config module includes the Config Manager and Screen for handling general, audio and video configuration settings of the GDK.

Control settings:

ConfigMgr automatically uses below default configuration:

iMTFriendly: 0 (disabled)
Audio.bInit: false (disabled)
Audio.iDriver: 0 (use default audio driver)
Audio.eAS: AS_16 (16 bit sampling)
Audio.eAF: AF_NORMAL (22050Hz)
Audio.eAM: AM_STEREO
Audio.iMusicVol: 128 (from 0 to 255)
Audio.iSoundVol: 128 (from 0 to 255)
Audio.iMixingChannels: 8 (up to 8 audio mixing channels)
Default screen with:
Driver: CRD_DEFAULT (use default renderer driver)
Batching: 1 (enabled)
Width x Height: 800 x 600
Logical size 800 x 600
Position: SDL_WINDOWPOS_UNDEFINED
Name: CRM64Pro GDK Application
Window flags: SDL_WINDOW_SHOWN
Window border: 1 (show window border)
Vertical sync: 0 (disabled)
Icon: default GDK icon
Clip region: no clip region set
Aspect ratio: letterbox

The configuration can be modified using provided methods.
In addition, methods for saving and loading the current configuration (general, audio and video) are provided.

This is a standard manager: objects are not shared and must be unique using its name as the key, in other words, you can not create an object with the same name of another one already created.

Only a single instance of the Configuration Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::IConfigMgr() method.

Note
The Configuration Manager is automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding resource leaks.

Classes

class  CRM64Pro::Screen
 Screen Object class. More...
 
class  CRM64Pro::ConfigMgr
 Config Manager class. More...
 

Enumerations

enum  CRM64Pro::eConfigAudioDriver {
  CRM64Pro::CAD_DEFAULT = 0 , CRM64Pro::CAD_WASAPI = 1 , CRM64Pro::CAD_DIRECTSOUND = 2 , CRM64Pro::CAD_WINMM = 3 ,
  CRM64Pro::CAD_ERROR = -1
}
 Audio drivers. More...
 
enum  CRM64Pro::eAudioFreq { CRM64Pro::AF_DEFAULT = 0 , CRM64Pro::AF_NORMAL = 22050 , CRM64Pro::AF_HIGH = 44100 , CRM64Pro::AF_ULTRA = 48000 }
 Audio frequency. More...
 
enum  CRM64Pro::eAudioSample { CRM64Pro::AS_DEFAULT = 0 , CRM64Pro::AS_8 = AUDIO_S8 , CRM64Pro::AS_16 = AUDIO_S16SYS , CRM64Pro::AS_32 = AUDIO_F32SYS }
 Audio sample. More...
 
enum  CRM64Pro::eAudioMode {
  CRM64Pro::AM_DEFAULT = 0 , CRM64Pro::AM_MONO = 1 , CRM64Pro::AM_STEREO = 2 , CRM64Pro::AM_SURROUND = 4 ,
  CRM64Pro::AM_SURROUNDPLUS = 6
}
 Audio mode. More...
 
enum  CRM64Pro::eConfigRendererDriver {
  CRM64Pro::CRD_DEFAULT = 0 , CRM64Pro::CRD_SOFTWARE = 1 , CRM64Pro::CRD_OPENGL = 2 , CRM64Pro::CRD_OPENGLES2 = 3 ,
  CRM64Pro::CRD_DIRECT3D = 4 , CRM64Pro::CRD_DIRECT3D11 = 5 , CRM64Pro::CRD_X11 = 6 , CRM64Pro::CRD_ERROR = -1
}
 Screen renderer drivers. More...
 
enum  CRM64Pro::eConfigScreenMode { CRM64Pro::CSM_WINDOW = 0 , CRM64Pro::CSM_FULLSCREEN = 1 , CRM64Pro::CSM_FULLSCREENWINDOW = 2 }
 Screen modes. More...
 
enum  CRM64Pro::eConfigScreenAspectRatio { CRM64Pro::CSA_LETTERBOX = 0 , CRM64Pro::CSA_OVERSCAN = 1 }
 Screen aspect ratio. More...
 

Functions

Sint32 CRM64Pro::Screen::info (Sint32 iMode=0)
 Request screen object information.
 
Sint32 CRM64Pro::Screen::getName (string &sName)
 Get the name.
 
Uint32 CRM64Pro::Screen::getID ()
 Get the ID.
 
Sint32 CRM64Pro::Screen::show ()
 Show the screen.
 
Sint32 CRM64Pro::Screen::hide ()
 Hide the screen.
 
Sint32 CRM64Pro::Screen::status ()
 Get the screen status.
 
Sint32 CRM64Pro::Screen::setIcon (SDL_Surface *suIcon)
 Set an icon.
 
Sint32 CRM64Pro::Screen::setDriver (eConfigRendererDriver eCRD)
 Set the renderer driver.
 
eConfigRendererDriver CRM64Pro::Screen::getDriver ()
 Get the renderer driver.
 
eConfigRendererDriver CRM64Pro::Screen::getDriverInUse ()
 Get the renderer driver in use.
 
Sint32 CRM64Pro::Screen::setVSync (Uint32 bFlag)
 Set the VSync mode.
 
Uint32 CRM64Pro::Screen::getVSync ()
 Get current VSync mode.
 
Sint32 CRM64Pro::Screen::setRenderBatching (Uint32 bFlag)
 Set the batching mode.
 
Uint32 CRM64Pro::Screen::getRenderBatching ()
 Get current batching mode.
 
Sint32 CRM64Pro::Screen::setMode (eConfigScreenMode eCSM)
 Set the screen mode.
 
eConfigScreenMode CRM64Pro::Screen::getMode ()
 Get the screen mode.
 
Sint32 CRM64Pro::Screen::setSize (Sint32 iWidth, Sint32 iHeight)
 Set the size of the screen.
 
Sint32 CRM64Pro::Screen::getSize (Sint32 *iWidth, Sint32 *iHeight)
 Get the size of the screen.
 
Sint32 CRM64Pro::Screen::setLogicalSize (Sint32 iWidth, Sint32 iHeight, eConfigScreenAspectRatio eCSA=CSA_LETTERBOX)
 Set the logic size of the screen.
 
Sint32 CRM64Pro::Screen::getLogicalSize (Sint32 *iWidth, Sint32 *iHeight, eConfigScreenAspectRatio *eCSA)
 Get the logical size of the screen.
 
Sint32 CRM64Pro::Screen::setPosition (Sint32 iX, Sint32 iY)
 Set the position.
 
Sint32 CRM64Pro::Screen::getPosition (Sint32 *iX, Sint32 *iY)
 Get the position.
 
Sint32 CRM64Pro::Screen::setClipRect (SDL_Rect *rClip)
 Set clipping rect.
 
Sint32 CRM64Pro::Screen::getClipRect (SDL_Rect *rClip)
 Get clipping rect.
 
Sint32 CRM64Pro::Screen::setTitle (const string &sName)
 Set the title.
 
Sint32 CRM64Pro::Screen::getTitle (string &sName)
 Get the title.
 
Sint32 CRM64Pro::Screen::setBorder (Uint32 bFlag)
 Set the border for the screen.
 
Uint32 CRM64Pro::Screen::getBorder ()
 Get the border for the screen.
 
SDL_Window * CRM64Pro::Screen::getWindow ()
 Get the SDL_Window associated to this screen.
 
SDL_Renderer * CRM64Pro::Screen::getRenderer ()
 Get the SDL_Renderer associated to this screen.
 
SDL_Surface * CRM64Pro::Screen::getSnapshot ()
 Get a SDL_Surface with a screen snapshot.
 
Sint32 CRM64Pro::Screen::getSnapshot (const string &sFile)
 Save the screen snapshot to an external PNG file.
 
Sint32 CRM64Pro::Screen::clear (Uint8 iR=0, Uint8 iG=0, Uint8 iB=0, Uint8 iA=255)
 Clear the screen.
 
Sint32 CRM64Pro::Screen::setRenderCallback (Sint32(*myRenderFunc)(Sint32 iMode, void *pObj), void *pObj=nullptr)
 Set a callback function for rendering your graphics at Render Frame Rate.
 
Sint32 CRM64Pro::Screen::fadeToColor (Uint8 iR, Uint8 iG, Uint8 iB, Sint32 iTime, SDL_Rect *rDst=nullptr)
 Perform a fade effect of this screen to the given color.
 
Sint32 CRM64Pro::Screen::fadeToImage (Sint32 idImage, Sint32 iTime, SDL_Rect *rDst=nullptr, SDL_Rect *rSrc=nullptr)
 Perform a fade effect of this screen to the given Image handler.
 
Sint32 CRM64Pro::ConfigMgr::info (Sint32 iMode=0)
 Request Configuration Manager information.
 
Sint32 CRM64Pro::ConfigMgr::audioInit (eAudioFreq eAF=AF_DEFAULT, eAudioSample eAS=AS_DEFAULT, eAudioMode eAM=AM_DEFAULT)
 Initialize the audio system.
 
Sint32 CRM64Pro::ConfigMgr::audioStatus (eAudioFreq *eAF=nullptr, eAudioSample *eAS=nullptr, eAudioMode *eAM=nullptr)
 Check audio system status.
 
Sint32 CRM64Pro::ConfigMgr::audioClose ()
 Close the audio system.
 
Sint32 CRM64Pro::ConfigMgr::audioSetDriver (eConfigAudioDriver eCAD)
 Set the audio driver.
 
eConfigAudioDriver CRM64Pro::ConfigMgr::audioGetDriver ()
 Get the audio driver.
 
eConfigAudioDriver CRM64Pro::ConfigMgr::audioGetDriverInUse ()
 Get the audio driver in use.
 
Sint32 CRM64Pro::ConfigMgr::audioMusicVolume (Sint32 iVolume)
 Music volume control.
 
Sint32 CRM64Pro::ConfigMgr::audioSoundVolume (Sint32 iVolume)
 Sound volume control.
 
Sint32 CRM64Pro::ConfigMgr::audioMixingChannels (Sint32 iNum)
 Manage sound mixing channels.
 
Sint32 CRM64Pro::ConfigMgr::audioHook (void(*mix_func)(void *udata, Uint8 *stream, Sint32 len), void *arg)
 Set a function that is called after all mixing is performed.
 
Sint32 CRM64Pro::ConfigMgr::create (const string &sName, Uint32 iUnused=0)
 Create a new screen.
 
Sint32 CRM64Pro::ConfigMgr::close (Sint32 idScreen)
 Close and destroy a screen.
 
Sint32 CRM64Pro::ConfigMgr::getNum ()
 Get number of loaded objects.
 
Sint32 CRM64Pro::ConfigMgr::setName (Sint32 idScreen, const string &sName)
 Change the object name.
 
void CRM64Pro::ConfigMgr::reset (Sint32 iMode=0)
 Set all default values, close audio system, remove all existing screens and create the "default" screen.
 
ScreenCRM64Pro::ConfigMgr::get (Sint32 idScreen=0)
 Get a pointer to the screen using its handler.
 
ScreenCRM64Pro::ConfigMgr::get (SDL_Window *wScreen)
 Get a pointer to the screen using a SDL_Window pointer.
 
Sint32 CRM64Pro::ConfigMgr::save (const string &sConfigXML, const string &sCDC="")
 Save current audio/screens configuration.
 
Sint32 CRM64Pro::ConfigMgr::load (const string &sConfigXML, const string &sCDC="")
 Load audio/screen configuration.
 
Sint32 CRM64Pro::ConfigMgr::setup (const string &sConfigXML, Sint32 idConfigCDC, const string &sCustomSetupXML="")
 Open the setup window for configurating audio/screen settings.
 
Sint32 CRM64Pro::ConfigMgr::setup (const string &sConfigXML, const string &sConfigCDC="", const string &sCustomSetupXML="")
 Open the setup window for configurating audio/screen settings.
 

Enumeration Type Documentation

◆ eConfigAudioDriver

Audio drivers.

Enumerator
CAD_DEFAULT 

Used in Config::audioSetDriver(), uses the default audio driver (default value).

CAD_WASAPI 

Used in Config::audioSetDriver(), uses WASAPI driver. Only for Win32/Win64.

CAD_DIRECTSOUND 

Used in Config::audioSetDriver(), uses DirectSound driver. Only for Win32/Win64.

CAD_WINMM 

Used in Config::audioSetDriver(), uses Windows Multimedia API. Only for Win32/Win64.

CAD_ERROR 

Returned by Config::audioGetDriver() if the method call failed.

◆ eAudioFreq

Audio frequency.

Enumerator
AF_DEFAULT 

Default value.

AF_NORMAL 

22050 Hz output.

AF_HIGH 

44100 Hz output.

AF_ULTRA 

48000 Hz output.

◆ eAudioSample

Audio sample.

Enumerator
AS_DEFAULT 

Default value.

AS_8 

8bits samples output.

AS_16 

16bits samples output.

AS_32 

32bits floating point samples output.

◆ eAudioMode

Audio mode.

Enumerator
AM_DEFAULT 

Default value.

AM_MONO 

Mono output.

AM_STEREO 

Stereo output.

AM_SURROUND 

Surround output.

AM_SURROUNDPLUS 

Surround with center and lfe.

◆ eConfigRendererDriver

Screen renderer drivers.

Enumerator
CRD_DEFAULT 

Used in Screen::setDriver(), uses the default renderer driver (default value).

CRD_SOFTWARE 

Used in Screen::setDriver(), uses a software renderer driver, it is slow but works on all platforms.

CRD_OPENGL 

Used in Screen::setDriver(), uses OpenGL renderer driver. Supported on Win32/Win64/Linux/MacOS X.

CRD_OPENGLES2 

Used in Screen::setDriver(), uses OpenGL ES v2.0 renderer driver. Supported on Android/iOS.

CRD_DIRECT3D 

Used in Screen::setDriver(), uses Direct3D v9 renderer driver. Only for Win32/Win64.

CRD_DIRECT3D11 

Used in Screen::setDriver(), uses Direct3D v11 renderer driver. Only for Win32/Win64 (needs Windows 8+).

CRD_X11 

Used in Screen::setDriver(), uses X11 renderer driver. Only for Linux.

CRD_ERROR 

Returned by Screen::getDriver() in case of error.

◆ eConfigScreenMode

Screen modes.

Enumerator
CSM_WINDOW 

Used in Screen::setMode(), uses a windowed mode (default value).

CSM_FULLSCREEN 

Used in Screen::setMode(), uses a real fullscreen mode which changes the monitor video mode.

CSM_FULLSCREENWINDOW 

Used in Screen::setMode(), uses a fullscreen window mode which takes the size of the desktop.

◆ eConfigScreenAspectRatio

Screen aspect ratio.

Enumerator
CSA_LETTERBOX 

Used in Screen::setLogicalSize(), keep the original aspect ratio using(if needed) as filler the required side-bars (default value).

CSA_OVERSCAN 

Used in Screen::setLogicalSize(), expand to fill the entire screen, even if some parts draw off the screen. CRD_DIRECT3D does not support this value.

Function Documentation

◆ info() [1/2]

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

Request screen object 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.

◆ getName()

Sint32 CRM64Pro::Screen::getName ( string &  sName)

Get the name.

Parameters
sNamea string containing the screen name.
Returns
0 on success or a negative error code on failure.

◆ getID()

Uint32 CRM64Pro::Screen::getID ( )

Get the ID.

Returns
the object ID.

◆ show()

Sint32 CRM64Pro::Screen::show ( )

Show the screen.

This method make the associated window to become visible.
If the screen was not shown before, it creates all needed internal attributes and initialize the screen.
If the screen was hidden, it is shown again without affecting any other attributes.

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

◆ hide()

Sint32 CRM64Pro::Screen::hide ( )

Hide the screen.

When a screen is hidden, its associated window is hidden but all attributes are kept.
This screen can be shown again using show() or closed using ConfigMgr::close().

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

◆ status()

Sint32 CRM64Pro::Screen::status ( )

Get the screen status.

Returns
C64_STATUS_DISABLEDscreen is uninitialized.
C64_STATUS_HIDDENscreen is initialized but hidden.
C64_STATUS_SHOWNscreen is initialized and visible.

◆ setIcon()

Sint32 CRM64Pro::Screen::setIcon ( SDL_Surface *  suIcon)

Set an icon.

It is used as the window icon.
Once you call this method, you can free the used surface as it is not longer needed.
The screen can be already initialized or not, when calling this method.

Parameters
suIconSDL_Surface pointer with the icon.
Returns
0 on success or a negative error code on failure.

◆ setDriver()

Sint32 CRM64Pro::Screen::setDriver ( eConfigRendererDriver  eCRD)

Set the renderer driver.

Parameters
eCRDscreen renderer driver. Check eConfigRendererDriver enum for further information.
Returns
0 on success or a negative error code on failure.
Note
A change of the renderer driver will destroy all created textures for this screen.
They will be automatically re-built when needed but also can be built in advance using ImageMgr::optimize() or Screen::optimize().

◆ getDriver()

eConfigRendererDriver CRM64Pro::Screen::getDriver ( )

Get the renderer driver.

This method return the renderer driver set by default or by setDriver() method.
Note that it could be different to the driver in use, for example, you could set CRD_DEFAULT and the driver in use will be CRD_SOFTWARE, CRD_OPENGL, etc.
For getting the driver in use, you can call to getDriverInUse() method.

Returns
eConfigRendererDriver enum value on success or CRD_ERROR code on failure.

◆ getDriverInUse()

eConfigRendererDriver CRM64Pro::Screen::getDriverInUse ( )

Get the renderer driver in use.

This method return the renderer driver in use, therefore the screen must be initialized.
For getting the driver set by default or by setDriver(), you can use getDriver() method.

Returns
eConfigRendererDriver enum value on success or CRD_ERROR code on failure.

◆ setVSync()

Sint32 CRM64Pro::Screen::setVSync ( Uint32  bFlag)

Set the VSync mode.

Enabling the vertical sync. will synchronize the screen rendering with the monitor refresh rate.
In addition, enabling it will limit the maximum Render Frame Rate, check Timer::setRate() for further information.

Parameters
bFlag0 for disabling and 1 for enabling it.
Common monitor refresh rates are 60, 70, 75, 120 or 155.
Returns
0 on success or a negative error code on failure.

◆ getVSync()

Uint32 CRM64Pro::Screen::getVSync ( )

Get current VSync mode.

Returns
0 if VSync is disabled, 1 if it is enabled.

◆ setRenderBatching()

Sint32 CRM64Pro::Screen::setRenderBatching ( Uint32  bFlag)

Set the batching mode.

SDL2's 2D Render API immediately dispatches any draw request to the GPU which could not be very efficient.
When the batching system is enabled, the draw requests are stored in batches and then dispatched to the GPU when needed.
This can reduce rendering overhead and increase the performance but it depends on the GPU and render driver used. For further information and benchmarks, you can check http://www.megastormssytems.com/cc-code/sdl-benchmark

Parameters
bFlag0 for disabling and 1 for enabling it.
Returns
0 on success or a negative error code on failure.
Note
A change of the batching system will recreate the renderer, hence, destroying all created textures for this screen.
They will be automatically re-built when needed but also can be built in advance using ImageMgr::optimize() or Screen::optimize().

◆ getRenderBatching()

Uint32 CRM64Pro::Screen::getRenderBatching ( )

Get current batching mode.

Returns
0 if batching system is disabled, 1 if it is enabled.

◆ setMode()

Sint32 CRM64Pro::Screen::setMode ( eConfigScreenMode  eCSM)

Set the screen mode.

Parameters
eCSMscreen mode. Check eConfigScreenMode enum for further information.
Returns
0 on success or a negative error code on failure.
Note
A change of the mode will destroy all created textures for this screen.
They will be automatically re-built when needed but also can be built in advance using ImageMgr::optimize() or Screen::optimize().

◆ getMode()

eConfigScreenMode CRM64Pro::Screen::getMode ( )

Get the screen mode.

Returns
eConfigScreenMode enum value on success.

◆ setSize()

Sint32 CRM64Pro::Screen::setSize ( Sint32  iWidth,
Sint32  iHeight 
)

Set the size of the screen.

We also change the logical size of the screen.

Parameters
iWidthscreen width.
iHeightscreen height.
Returns
0 on success or a negative error code on failure.
Note
If the screen is using CSM_FULLSCREEN or CSM_FULLSCREENWINDOW, the size can not be changed.
A change of the size will destroy all created textures for this screen.
They will be automatically re-built when needed but also can be built in advance using ImageMgr::optimize() or Screen::optimize().

◆ getSize()

Sint32 CRM64Pro::Screen::getSize ( Sint32 *  iWidth,
Sint32 *  iHeight 
)

Get the size of the screen.

This method return the size of the screen's client area.

Parameters
iWidthan integer pointer filled in with screen width.
If nullptr is passed, the method ignores the retrieving of this value.
iHeightan integer pointer filled in with screen height.
If nullptr is passed, the method ignores the retrieving of this value.
Returns
0 on success or a negative error code on failure.

◆ setLogicalSize()

Sint32 CRM64Pro::Screen::setLogicalSize ( Sint32  iWidth,
Sint32  iHeight,
eConfigScreenAspectRatio  eCSA = CSA_LETTERBOX 
)

Set the logic size of the screen.

Allows a device independent resolution rendering.

Parameters
iWidthlogical screen width. A negative value for not modifying this value.
iHeightlogical screen height. A negative value for not modifying this value.
eCSAset the aspect ratio adjustment. Check eConfigScreenAspectRatio enum for further information. By default, it is set to CSA_LETTERBOX.
Returns
0 on success or a negative error code on failure.
Note
CRD_DIRECT3D driver does not support CSA_OVERSCAN mode.

◆ getLogicalSize()

Sint32 CRM64Pro::Screen::getLogicalSize ( Sint32 *  iWidth,
Sint32 *  iHeight,
eConfigScreenAspectRatio eCSA 
)

Get the logical size of the screen.

This method return the size of the logical screen and the current aspect ratio mode.

Parameters
iWidthan integer pointer filled in with screen width.
If nullptr is passed, the method ignores the retrieving of this value.
iHeightan integer pointer filled in with screen height.
If nullptr is passed, the method ignores the retrieving of this value.
eCSAa eConfigScreenAspectRatio enum pointer filled in with the aspect ratio adjustment.
If nullptr is passed, the method ignores the retrieving of this value.
Returns
0 on success or a negative error code on failure.

◆ setPosition()

Sint32 CRM64Pro::Screen::setPosition ( Sint32  iX,
Sint32  iY 
)

Set the position.

Parameters
iXscreen X position.
iYscreen Y position.
Returns
0 on success or a negative error code on failure.

◆ getPosition()

Sint32 CRM64Pro::Screen::getPosition ( Sint32 *  iX,
Sint32 *  iY 
)

Get the position.

This method return the position of a screen.

Parameters
iXa pointer filled in with screen X position.
If nullptr is passed, the method ignores the retrieving of this value.
iYa pointer filled in with screen Y position.
If nullptr is passed, the method ignores the retrieving of this value.
Returns
0 on success or a negative error code on failure.

◆ setClipRect()

Sint32 CRM64Pro::Screen::setClipRect ( SDL_Rect *  rClip)

Set clipping rect.

Parameters
rClippointer to SDL_Rect structure with the clipping area.
nullptr for disabling it.
Returns
0 on success or a negative error code on failure.

◆ getClipRect()

Sint32 CRM64Pro::Screen::getClipRect ( SDL_Rect *  rClip)

Get clipping rect.

Parameters
rClippointer to SDL_Rect structure filled in with current clipping area.
Returns
0 on success or a negative error code on failure.

◆ setTitle()

Sint32 CRM64Pro::Screen::setTitle ( const string &  sName)

Set the title.

It is used as window title.
The screen can be already initialized or not when calling this method.

Parameters
sNametitle for the screen.
Returns
0 on success or a negative error code on failure.

◆ getTitle()

Sint32 CRM64Pro::Screen::getTitle ( string &  sName)

Get the title.

Parameters
sNamea string variable.
Will not be modified when the screen does not exist.
Returns
0 on success or a negative error code on failure.

◆ setBorder()

Sint32 CRM64Pro::Screen::setBorder ( Uint32  bFlag)

Set the border for the screen.

The screen border is only visible on CSM_WINDOW mode so it only has effect on this mode.

Parameters
bFlag0 for disabling and 1 for enabling it.
Returns
0 on success or a negative error code on failure.

◆ getBorder()

Uint32 CRM64Pro::Screen::getBorder ( )

Get the border for the screen.

Returns
0 if the border is disabled, 1 if it is enabled.

◆ getWindow()

SDL_Window * CRM64Pro::Screen::getWindow ( )

Get the SDL_Window associated to this screen.

Returns
a pointer to the SDL_Window or nullptr on failure.
Warning
Use carefully this method and in general, only for read-only checks.

◆ getRenderer()

SDL_Renderer * CRM64Pro::Screen::getRenderer ( )

Get the SDL_Renderer associated to this screen.

Returns
a pointer to the SDL_Renderer or nullptr on failure.
Warning
Use carefully this method and in general, only for read-only checks.

◆ getSnapshot() [1/2]

SDL_Surface * CRM64Pro::Screen::getSnapshot ( )

Get a SDL_Surface with a screen snapshot.

Returns
a pointer to the SDL_Surface or nullptr on failure.
The created surface must be removed by the user to avoid a resource leak.
Note
Getting a screen snapshot is quite slow.

◆ getSnapshot() [2/2]

Sint32 CRM64Pro::Screen::getSnapshot ( const string &  sFile)

Save the screen snapshot to an external PNG file.

Parameters
sFilestring containing the [directory]+filename+[extension].
Returns
0 on success or a negative error code on failure.
Note
Getting a screen snapshot is quite slow.

◆ clear()

Sint32 CRM64Pro::Screen::clear ( Uint8  iR = 0,
Uint8  iG = 0,
Uint8  iB = 0,
Uint8  iA = 255 
)

Clear the screen.

Parameters
iRThe red color value. Default is 0.
iGThe green color value. Default is 0.
iBThe blue color value. Default is 0.
iAThe alpha value. Default is 255.
Returns
0 on success or a negative error code on failure.

◆ setRenderCallback()

Sint32 CRM64Pro::Screen::setRenderCallback ( Sint32(*)(Sint32 iMode, void *pObj)  myRenderFunc,
void *  pObj = nullptr 
)

Set a callback function for rendering your graphics at Render Frame Rate.

Parameters
myRenderFuncpointer to your graphics rendering function or nullptr for removing current assigned function.
iMode will be set to 1 right after a Logic Frame update.
pObj a pointer to the data/function/static method fixed when calling this method.
pObjpointer to data/function/static method.
By default, it is not used and set to nullptr.
Returns
0 on success or a negative error code on failure.
Note
There are some alternative ways of rendering your graphics at Render Frame Rate, but the best one is to use a callback function.
For further information, please check Rendering your graphics: standard and advance methods.

◆ fadeToColor()

Sint32 CRM64Pro::Screen::fadeToColor ( Uint8  iR,
Uint8  iG,
Uint8  iB,
Sint32  iTime,
SDL_Rect *  rDst = nullptr 
)

Perform a fade effect of this screen to the given color.

Parameters
iRThe red color value.
iGThe green color value.
iBThe blue color value.
iTimeduration in milliseconds for performing the effect.
Minimum of 50ms and maximum of 10000ms.
rDstthe destination SDL_Rect structure or nullptr for using the whole screen size.
By default, it is set to nullptr.
Returns
0 on success or a negative error code on failure.
Note
This method will "block" the execution until the duration is over and the effect done.

◆ fadeToImage()

Sint32 CRM64Pro::Screen::fadeToImage ( Sint32  idImage,
Sint32  iTime,
SDL_Rect *  rDst = nullptr,
SDL_Rect *  rSrc = nullptr 
)

Perform a fade effect of this screen to the given Image handler.

Parameters
idImageImage handler
iTimeduration in milliseconds for performing the effect.
Minimum of 50ms and maximum of 10000ms.
rDstthe destination SDL_Rect structure or nullptr for using the whole screen size.
By default, it is set to nullptr.
rSrcthe image source SDL_Rect structure or nullptr for using the whole image.
By default, it is set to nullptr.
Returns
0 on success or a negative error code on failure.
Note
This method will "block" the execution until the duration is over and the effect done.

◆ info() [2/2]

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

Request Configuration Manager information.

For displaying the information, it uses the default log.

  • General information: multithread friendly flag
  • Graphics information: number of displays, renderer drivers availables and screens
  • Audio information: audio devices, audio drivers and current audio output
Parameters
iMode-1 for displaying only Manager information.
0 for displaying Manager and all Objects information. This is the default value.
idScreen for displaying Manager and given Screen id information.
Returns
0 on success or a negative error code on failure.

◆ audioInit()

Sint32 CRM64Pro::ConfigMgr::audioInit ( eAudioFreq  eAF = AF_DEFAULT,
eAudioSample  eAS = AS_DEFAULT,
eAudioMode  eAM = AM_DEFAULT 
)

Initialize the audio system.

If the audio system is initialized, this method closes it and try to open with new parameters.

Parameters
eAFAudio frequency. Check eAudioFreq enum for further information.
eASAudio sampling. Check eAudioSample enum for further information.
eAMAudio mode. Check eAudioMode enum for further information.
Returns
0 on success or a negative error code on failure.

◆ audioStatus()

Sint32 CRM64Pro::ConfigMgr::audioStatus ( eAudioFreq eAF = nullptr,
eAudioSample eAS = nullptr,
eAudioMode eAM = nullptr 
)

Check audio system status.

Parameters
eAFeAudioFreq enum pointer filled in with audio frequency.
If nullptr is passed (value by default), the method ignores the retrieving of this value.
eASeAudioSample enum pointer filled in with audio sampling.
If nullptr is passed (value by default), the method ignores the retrieving of this value.
eAMeAudioMode enum pointer filled in with audio mode.
If nullptr is passed (value by default), the method ignores the retrieving of this value.
Returns
0 on success (audio output is enabled) or -1 value when audio output is disabled.

◆ audioClose()

Sint32 CRM64Pro::ConfigMgr::audioClose ( )

Close the audio system.

It is recommended to call this method at the very end of your application, once you have closed/removed all your resources and right before the call to Main::Terminate().
In any case, if not called by your application, it will be automatically called on Main::Terminate()

Warning
When closing the audio system, all loaded musics are also cleaned up. If your application is still running, you have to reload musics resources. Note audio resources are kept.
Returns
0 on success or a negative error code on failure.

◆ audioSetDriver()

Sint32 CRM64Pro::ConfigMgr::audioSetDriver ( eConfigAudioDriver  eCAD)

Set the audio driver.

Parameters
eCADaudio driver. Check eConfigAudioDriver enum for further information.
Returns
0 on success or a negative error code on failure.
Note
Once the audio is initialized, this method has not any effect.

◆ audioGetDriver()

eConfigAudioDriver CRM64Pro::ConfigMgr::audioGetDriver ( )

Get the audio driver.

This method return the audio driver set by default or by audioSetDriver() method.
Note that it could be different to the driver in use, for example, you could set CAD_DEFAULT and the driver in use will be CAD_WASAPI, CAD_WINMM, etc.
For getting the driver in use, you can call to audioGetDriverInUse() method.

Returns
eConfigAudioDriver enum value on success or CAD_ERROR code on failure.

◆ audioGetDriverInUse()

eConfigAudioDriver CRM64Pro::ConfigMgr::audioGetDriverInUse ( )

Get the audio driver in use.

This method return the audio driver in use, therefore the audio must be initialized.
For getting the driver set by default or by audioSetDriver(), you can use audioGetDriver() method.

Returns
eConfigAudioDriver enum value on success or CAD_ERROR code on failure.

◆ audioMusicVolume()

Sint32 CRM64Pro::ConfigMgr::audioMusicVolume ( Sint32  iVolume)

Music volume control.

Parameters
iVolumevolume ranging from 0 to 128.
A negative value has not any effect.
Returns
current music volume.

◆ audioSoundVolume()

Sint32 CRM64Pro::ConfigMgr::audioSoundVolume ( Sint32  iVolume)

Sound volume control.

The sound volume affects to all channels.

Parameters
iVolumevolume ranging from 0 to 128.
A negative value has not any effect.
Returns
current sound volume.

◆ audioMixingChannels()

Sint32 CRM64Pro::ConfigMgr::audioMixingChannels ( Sint32  iNum)

Manage sound mixing channels.

The mixing channels number can be modified at any time.

Parameters
iNumnumber of mixing channels or maximum number of sounds played at the same time.
Minimum of 8 (set it by default) and up to 128.
A negative value will do nothing just return current number of mixing channels.
Returns
greater than 0 specifying the number of mixing channels or a negative error code on failure.

◆ audioHook()

Sint32 CRM64Pro::ConfigMgr::audioHook ( void(*)(void *udata, Uint8 *stream, Sint32 len)  mix_func,
void *  arg 
)

Set a function that is called after all mixing is performed.

This can be used to provide real-time visual display of the audio stream or add a custom mixer filter for the stream data.

Parameters
mix_funcfunction pointer.
argpointer to extra arguments passed to the mixing function.
Returns
0 on success or a negative error code on failure.

◆ create()

Sint32 CRM64Pro::ConfigMgr::create ( const string &  sName,
Uint32  iUnused = 0 
)

Create a new screen.

Parameters
sNameThe name to give to the screen object (e.g. 'myScreen').
The object name must be unique and with a maximum size of 64 characters or will be truncated.
iUnusedunused for the time being.
Returns
greater than 0 on success(the Screen id) or a negative error code on failure.
Note
Once the screen is created, it is ready for being modified and eventually shown using Screen::show().

◆ close()

Sint32 CRM64Pro::ConfigMgr::close ( Sint32  idScreen)

Close and destroy a screen.

Parameters
idScreen0 for closing all screens or the Screen id.
This will totally remove the screen and all the specific resources associated to it (SDL window, SDL renderer, etc.).
In addition, it will inform the ImageMgr in order to remove all textures created for the screen.
Returns
0 on success or a negative error code on failure.
Note
If you forget to close a Screen, it will be automatically closed once the GDK is terminated.

◆ getNum()

Sint32 CRM64Pro::ConfigMgr::getNum ( )

Get number of loaded objects.

Returns
the number of screen objects.

◆ setName()

Sint32 CRM64Pro::ConfigMgr::setName ( Sint32  idScreen,
const string &  sName 
)

Change the object name.

Parameters
idScreenScreen id.
sNameThe name to give to the screen object (e.g. 'myScreen').
The object name must be unique and with a maximum size of 64 characters or will be truncated.
Returns
0 on success or a negative error code on failure.

◆ reset()

void CRM64Pro::ConfigMgr::reset ( Sint32  iMode = 0)

Set all default values, close audio system, remove all existing screens and create the "default" screen.

Parameters
iMode0 for resetting general, audio and screen values or 1 for resetting only the screen values.

◆ get() [1/2]

Screen * CRM64Pro::ConfigMgr::get ( Sint32  idScreen = 0)

Get a pointer to the screen using its handler.

Parameters
idScreenScreen id.
By default, it closes the default screen.
Returns
nullptr the screen object was not found or a valid pointer to the screen object.

◆ get() [2/2]

Screen * CRM64Pro::ConfigMgr::get ( SDL_Window *  wScreen)

Get a pointer to the screen using a SDL_Window pointer.

Parameters
wScreenSDL_Window pointer.
Returns
nullptr no screen with that SDL_Window found or a valid pointer to the screen object.

◆ save()

Sint32 CRM64Pro::ConfigMgr::save ( const string &  sConfigXML,
const string &  sConfigCDC = "" 
)

Save current audio/screens configuration.

Parameters
sConfigXMLstring containing the [directory]+filename+[extension] of the config XML file.
Directory separators '\' and '/' are supported.
sConfigCDCstring containing the [directory]+filename+[extension] of a CDC file where the config XML will be saved to.
Directory separators '\' and '/' are supported. This parameter is optional.
Returns
0 on success or a negative error code on failure.

◆ load()

Sint32 CRM64Pro::ConfigMgr::load ( const string &  sConfigXML,
const string &  sConfigCDC = "" 
)

Load audio/screen configuration.

Parameters
sConfigXMLstring containing the [directory]+filename+[extension] of the config XML file.
Directory separators '\' and '/' are supported.
sConfigCDCstring containing the [directory]+filename+[extension] of a CDC file that contains the config XML file.
Directory separators '\' and '/' are supported. This parameter is optional.
Returns
0 on success or a negative error code on failure.
Note
If audio or the screens are already initialized, they are re-initialized using these new settings.

◆ setup() [1/2]

Sint32 CRM64Pro::ConfigMgr::setup ( const string &  sConfigXML,
Sint32  idConfigCDC,
const string &  sCustomSetupXML = "" 
)

Open the setup window for configurating audio/screen settings.

Parameters
sConfigXMLstring containing the name of the config XML file.
idConfigCDCid of an open CDC file that contains the config XML and the custom setup XML files.
Directory separators '\' and '/' are supported. Using the id instead of the CDC name allows to open secured CDC files.
sCustomSetupXMLstring containing the name of the custom setup XML file. This parameter is optional.
Returns
0 on success or a negative error code on failure.
Note
By default, it uses a built-in layout.

◆ setup() [2/2]

Sint32 CRM64Pro::ConfigMgr::setup ( const string &  sConfigXML,
const string &  sConfigCDC = "",
const string &  sCustomSetupXML = "" 
)

Open the setup window for configurating audio/screen settings.

Parameters
sConfigXMLstring containing the name of the config XML file.
sConfigCDCstring containing the [directory]+filename+[extension] of a CDC file that contains the config and the custom setup XML files.
Directory separators '\' and '/' are supported.
sCustomSetupXMLstring containing the name of the custom setup XML file. This parameter is optional.
Returns
0 on success or a negative error code on failure.
Note
By default, it uses a built-in layout.