Description

Configuration Manager and Screen objects for general, audio and video settings [v25.11.0].

Overview

The Config module provides centralized management for all GDK configuration settings. It handles general behavior options, audio system parameters, and video/screen management. The module also provides methods for saving and loading the complete configuration state to/from external files.

Key features

General settings: Modify the behavior of general GDK settings (e.g., ConfigMgr::iMTFriendly)
Audio configuration: Enable/disable the audio system and configure its attributes
Video management: Add, modify and release screens (a screen is a top-level entity containing a SDL_Window and SDL_Renderer plus all its attributes)
Persistence: Save and load complete configuration state (general, audio and video)

Configuration areas

General	Core behavior settings affecting the overall GDK operation
Audio	Audio system initialization, driver selection, sampling, frequency, channels and volume
Video	Screen management including window properties, renderer settings and display options

Default configuration

The ConfigMgr automatically applies the following default values:

General settings

iMTFriendly	0 (disabled)

Audio settings

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.fMasterGain	1.0 (range: 0.0 to 2.0)
Audio.fMusicGain	1.0 (range: 0.0 to 2.0)
Audio.fSFXGain	1.0 (range: 0.0 to 2.0)
Audio.fVoiceGain	1.0 (range: 0.0 to 2.0)
Audio.fCustomGain	1.0 (range: 0.0 to 2.0)

Default screen settings

Driver	CRD_DEFAULT (use default renderer driver)
Width � Height	800 x 600
Logical presentation 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
Logical presentation mode	disabled
Logical presentation quality	nearest pixel sampling

Manager type

This is a standard manager: objects are not shared and must be unique using its name as the key. You cannot create an object with the same name as another one already created.

Best practices

Initialize the audio system via ConfigMgr::audioInit() or ConfigMgr::load() before using the Audio Track Manager
Use ConfigMgr::load() to restore a previously saved configuration at application startup
Use ConfigMgr::save() to persist user preferences before application exit
When creating multiple screens, ensure each has a unique name
Enable vertical sync to prevent screen tearing on displays with fixed refresh rates
Access the manager exclusively through Main::IConfigMgr()

Note: The Configuration Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::IConfigMgr() method.
The Configuration Manager is automatically released when Main::Terminate() is called. At this time, any resource still loaded will be released, avoiding 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_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 = SDL_AUDIO_U8 , CRM64Pro::AS_16 = SDL_AUDIO_S16 , CRM64Pro::AS_32 = SDL_AUDIO_F32 }
	Audio sample. More...
enum	CRM64Pro::eAudioMode { CRM64Pro::AM_DEFAULT = 0 , CRM64Pro::AM_MONO = 1 , CRM64Pro::AM_STEREO = 2 , CRM64Pro::AM_SURROUND21 = 3 , CRM64Pro::AM_QUAD = 4 , CRM64Pro::AM_SURROUND41 = 5 , CRM64Pro::AM_SURROUND51 = 6 , CRM64Pro::AM_SURROUND61 = 7 , CRM64Pro::AM_SURROUND71 = 8 }
	Audio mode. More...
enum	CRM64Pro::eConfigRendererDriver { CRM64Pro::CRD_DEFAULT = 0 , CRM64Pro::CRD_SOFTWARE = 1 , CRM64Pro::CRD_OPENGL = 2 , CRM64Pro::CRD_OPENGLES2 = 3 , CRM64Pro::CRD_VULKAN = 4 , CRM64Pro::CRD_DIRECT3D = 5 , CRM64Pro::CRD_DIRECT3D11 = 6 , CRM64Pro::CRD_DIRECT3D12 = 7 , CRM64Pro::CRD_X11 = 8 , CRM64Pro::CRD_METAL = 9 , CRM64Pro::CRD_GPU3D = 10 , CRM64Pro::CRD_ERROR = -1 }
	Screen renderer drivers. More...
enum	CRM64Pro::eConfigScreenMode { CRM64Pro::CSM_WINDOW = 0 , CRM64Pro::CSM_FULLSCREEN = 1 , CRM64Pro::CSM_FULLSCREENEXCLUSIVE = 2 }
	Screen modes. 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 () const
	Get the renderer driver.
eConfigRendererDriver	CRM64Pro::Screen::getDriverInUse () const
	Get the renderer driver in use.
Sint32	CRM64Pro::Screen::setVSync (Uint32 bFlag)
	Set the VSync mode.
Uint32	CRM64Pro::Screen::getVSync () const
	Get current VSync mode.
Sint32	CRM64Pro::Screen::setMode (eConfigScreenMode eCSM)
	Set the screen mode.
eConfigScreenMode	CRM64Pro::Screen::getMode () const
	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::setLogicalPresentation (Sint32 iWidth, Sint32 iHeight, SDL_RendererLogicalPresentation eSDL_RLP=SDL_LOGICAL_PRESENTATION_DISABLED)
	Set the logical presentation size of the screen.
Sint32	CRM64Pro::Screen::getLogicalPresentation (Sint32 iWidth=nullptr, Sint32 iHeight=nullptr, SDL_RendererLogicalPresentation *eSDL_RLP=nullptr) const
	Get the logical presentation 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 () const
	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_FRect *rDst=nullptr)
	Perform a fade effect of this screen to the given color.
Sint32	CRM64Pro::Screen::fadeToImage (Sint32 idImage, Sint32 iTime, SDL_FRect rDst=nullptr, SDL_FRect 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 () const
	Get the audio driver.
const char *	CRM64Pro::ConfigMgr::audioGetDriverInUse () const
	Get the audio driver name in use.
Sint32	CRM64Pro::ConfigMgr::audioSetMasterGain (float fGain)
	Set Master gain (Volume).
float	CRM64Pro::ConfigMgr::audioGetMasterGain () const
	Get Master gain (Volume).
Sint32	CRM64Pro::ConfigMgr::audioSetTagGain (eAudioTrackTag eTag, float fGain)
	Set Gain (Volume) for a specific audio track tag category.
float	CRM64Pro::ConfigMgr::audioGetTagGain (eAudioTrackTag eTag) const
	Get the current gain for a specific audio track tag category.
MIX_Mixer *	CRM64Pro::ConfigMgr::audioGetMixer () const
	Get the internal SDL3 Mixer Device handle.
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 () const
	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.
Screen *	CRM64Pro::ConfigMgr::get (Sint32 idScreen=0)
	Get a pointer to the screen using its handle.
Screen *	CRM64Pro::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 configuring audio/screen settings.
Sint32	CRM64Pro::ConfigMgr::setup (const string &sConfigXML, const string &sConfigCDC="", const string &sCustomSetupXML="")
	Open the setup window for configuring audio/screen settings.

Enumeration Type Documentation

◆ eConfigAudioDriver

enum CRM64Pro::eConfigAudioDriver

Audio drivers.

Enumerator
CAD_DEFAULT	Config::audioSetDriver(): use the platform default (WASAPI on Win64, PulseAudio on Linux, CoreAudio on macOS).
CAD_WASAPI	Config::audioSetDriver(): force WASAPI. Win64 only.
CAD_DIRECTSOUND	Config::audioSetDriver(): force DirectSound. Audio settings are adjustable. Win64 only.
CAD_ERROR	Returned by Config::audioGetDriver() when the call fails.

◆ eAudioFreq

enum CRM64Pro::eAudioFreq

Audio frequency.

Enumerator
AF_DEFAULT	Default sample rate.
AF_NORMAL	22050 Hz output.
AF_HIGH	44100 Hz output.
AF_ULTRA	48000 Hz output.

◆ eAudioSample

enum CRM64Pro::eAudioSample

Audio sample.

Enumerator
AS_DEFAULT	Default sample format.
AS_8	8-bit samples.
AS_16	16-bit samples.
AS_32	32-bit floating-point samples.

◆ eAudioMode

enum CRM64Pro::eAudioMode

Audio mode.

Enumerator
AM_DEFAULT	Default mode.
AM_MONO	Mono output.
AM_STEREO	Stereo output.
AM_SURROUND21	Surround 2.1 output.
AM_QUAD	Quad output.
AM_SURROUND41	Surround 4.1 output.
AM_SURROUND51	Surround 5.1 output.
AM_SURROUND61	Surround 6.1 output.
AM_SURROUND71	Surround 7.1 output.

◆ eConfigRendererDriver

enum CRM64Pro::eConfigRendererDriver

Screen renderer drivers.

Enumerator
CRD_DEFAULT	Screen::setDriver(): use the default renderer driver (default value).
CRD_SOFTWARE	Screen::setDriver(): software renderer driver. Slow but works on all platforms.
CRD_OPENGL	Screen::setDriver(): OpenGL renderer. Supported on Win64/Linux/macOS.
CRD_OPENGLES2	Screen::setDriver(): OpenGL ES v2.0 renderer. Supported on Android/iOS.
CRD_VULKAN	Screen::setDriver(): Vulkan renderer. Supported on Win64/Linux/macOS.
CRD_DIRECT3D	Screen::setDriver(): Direct3D v9 renderer. Win64 only.
CRD_DIRECT3D11	Screen::setDriver(): Direct3D v11 renderer. Win64 only (Windows 8+).
CRD_DIRECT3D12	Screen::setDriver(): Direct3D v12 renderer. Win64 only (Windows 10+).
CRD_X11	Screen::setDriver(): X11 renderer. Linux only.
CRD_METAL	Screen::setDriver(): Metal renderer. macOS only.
CRD_GPU3D	Screen::setDriver(): GPU 3D renderer. Supported on Win64/Linux/macOS.
CRD_ERROR	Returned by Screen::getDriver() on error.

◆ eConfigScreenMode

enum CRM64Pro::eConfigScreenMode

Screen modes.

Enumerator
CSM_WINDOW	Screen::setMode(): windowed mode (default).
CSM_FULLSCREEN	Screen::setMode(): fullscreen window that matches desktop size. Recommended fullscreen mode.
CSM_FULLSCREENEXCLUSIVE	Screen::setMode(): exclusive fullscreen that switches the monitor mode to the closest match for the requested resolution.

Function Documentation

◆ info() [1/2]

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

Request screen object information.

Writes screen information to the default log.

Parameters

iMode unused 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

sName a string reference filled in with the screen name.

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

◆ getID()

Uint32 CRM64Pro::Screen::getID ( )

Get the ID.

Returns: Object ID.

◆ show()

Sint32 CRM64Pro::Screen::show ( )

Show the screen.

Makes the associated window visible. If the screen was not previously shown, it creates all required internal attributes and initializes the screen. If the screen was hidden, it is shown again without altering existing attributes.

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

◆ hide()

Sint32 CRM64Pro::Screen::hide ( )

Hide the screen.

When hidden, the associated window is hidden but all attributes are kept. The 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_DISABLED if uninitialized, C64_STATUS_HIDDEN if initialized but hidden, or C64_STATUS_SHOWN if initialized and visible.

◆ setIcon()

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

Set an icon.

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

Parameters

suIcon SDL_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

eCRD	screen renderer driver. Check ::eConfigRendererDriver enum for details.

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

Note

Changing the renderer driver will:

Destroy all created textures for this screen (auto-rebuilt when needed, or rebuild in advance with ImageMgr::optimize() or Screen::optimize())
Recreate the screen (window and renderer)

◆ getDriver()

eConfigRendererDriver CRM64Pro::Screen::getDriver ( ) const

Get the renderer driver.

Returns the renderer driver set by default or by setDriver() method. Note that it could differ from the actual driver in use. For example, CRD_DEFAULT may resolve to CRD_SOFTWARE, CRD_OPENGL, etc. Use getDriverInUse() to get the actual driver in use.

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

◆ getDriverInUse()

eConfigRendererDriver CRM64Pro::Screen::getDriverInUse ( ) const

Get the renderer driver in use.

Returns the renderer driver currently in use. The screen must be initialized. Use getDriver() to get the driver set by default or by setDriver().

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

◆ setVSync()

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

Set the VSync mode.

Enabling VSync synchronizes screen rendering with the monitor refresh rate. Additionally, enabling it limits the maximum Render Frame Rate. See Timer::setRate() for details.

Parameters

bFlag 0 to disable, 1 to enable. 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 ( ) const

Get current VSync mode.

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

◆ setMode()

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

Set the screen mode.

Parameters

eCSM	screen mode. Check ::eConfigScreenMode enum for details.

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

Note

Changing the mode will:

Destroy all created textures for this screen (auto-rebuilt when needed, or rebuild in advance with ImageMgr::optimize() or Screen::optimize())
Recreate the screen (window and renderer)
When entering fullscreen mode, if resolution differs from application size and no logical presentation mode is set, one is set automatically
When entering window mode, if resolution and logical size match, presentation mode is disabled

◆ getMode()

eConfigScreenMode CRM64Pro::Screen::getMode ( ) const

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.

Parameters

iWidth	screen width.
iHeight	screen height.

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

Note: The size cannot be changed in ::CSM_FULLSCREEN or ::CSM_FULLSCREENEXCLUSIVE modes.

◆ getSize()

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

Get the size of the screen.

Returns the size of the screen's client area.

Parameters

iWidth	an integer pointer filled in with screen width. If nullptr, this value is not retrieved.
iHeight	an integer pointer filled in with screen height. If nullptr, this value is not retrieved.

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

◆ setLogicalPresentation()

Sint32 CRM64Pro::Screen::setLogicalPresentation	(	Sint32	iWidth,
		Sint32	iHeight,
		SDL_RendererLogicalPresentation	eSDL_RLP = SDL_LOGICAL_PRESENTATION_DISABLED )

Set the logical presentation size of the screen.

Allows a device independent resolution rendering.

Parameters

iWidth	logical presentation width. A negative value for not modifying this value.
iHeight	logical presentation height. A negative value for not modifying this value.
eSDL_RLP	set the logical presentation mode. Check SDL_RendererLogicalPresentation for further information. By default, it is set to SDL_LOGICAL_PRESENTATION_DISABLED.

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

◆ getLogicalPresentation()

Sint32 CRM64Pro::Screen::getLogicalPresentation	(	Sint32 *	iWidth = nullptr,
		Sint32 *	iHeight = nullptr,
		SDL_RendererLogicalPresentation *	eSDL_RLP = nullptr ) const

Get the logical presentation size of the screen.

Returns the logical presentation size and mode for this screen.

Parameters

iWidth	an integer pointer filled in with logical presentation width. If nullptr, this value is not retrieved.
iHeight	an integer pointer filled in with logical presentation height. If nullptr, this value is not retrieved.
eSDL_RLP	a SDL_RendererLogicalPresentation enum pointer filled in with the logical presentation mode. If nullptr, this value is not retrieved.

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

◆ setPosition()

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

Set the position.

Parameters

iX	screen X position.
iY	screen 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.

Returns the position of a screen.

Parameters

iX	a pointer filled in with screen X position. If nullptr, this value is not retrieved.
iY	a pointer filled in with screen Y position. If nullptr, this value is not retrieved.

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

◆ setClipRect()

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

Set clipping rect.

Parameters

rClip pointer to SDL_Rect structure with the clipping area, or nullptr to disable clipping.

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

◆ getClipRect()

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

Get clipping rect.

Parameters

rClip pointer to SDL_Rect structure filled in with current clipping area when clipping is enabled.

Returns: 1 if clipping is enabled, 0 if clipping is disabled, or a negative error code on failure.

◆ setTitle()

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

Set the title.

Sets the window title. The screen can be initialized or not when calling this method.

Parameters

sName title 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

sName a string reference filled in with the window title.

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

bFlag 0 for disabling and 1 for enabling it.

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

◆ getBorder()

Uint32 CRM64Pro::Screen::getBorder ( ) const

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

sFile string 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

iR	The red color value. Default is 0.
iG	The green color value. Default is 0.
iB	The blue color value. Default is 0.
iA	The alpha value. Default is 255.

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

◆ setRenderCallback()

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.

Parameters

myRenderFunc	pointer to your graphics rendering function or nullptr to remove current assigned function. The iMode parameter of the callback is set to 1 right after a Logic Frame update.
pObj	pointer to user data passed to the callback function. By default nullptr.

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

Note: There are alternative ways of rendering graphics at Render Frame Rate, but using a callback function is recommended. See Rendering your graphics: standard and advance methods for details.

◆ fadeToColor()

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

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

Parameters

iR	The red color value.
iG	The green color value.
iB	The blue color value.
iTime	duration in milliseconds (minimum 50ms, maximum 10000ms).
rDst	the destination SDL_FRect structure or nullptr for whole screen (default).

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

Note: This method blocks execution until the effect completes. Best suited for short durations (up to 1000ms).

◆ fadeToImage()

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

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

Parameters

idImage	Image handler.
iTime	duration in milliseconds (minimum 50ms, maximum 10000ms).
rDst	the destination SDL_FRect structure or nullptr for whole screen (default).
rSrc	the image source SDL_FRect structure or nullptr for whole image (default).

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

Note: This method blocks execution until the effect completes. Best suited for short durations (up to 1000ms).

◆ info() [2/2]

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

Request Configuration Manager information.

Writes manager information to the default log. Displays: general settings (multithread friendly flag), graphics information (displays, renderer drivers, screens), and audio information (devices, drivers, output).

Parameters

iMode -1 to display only manager information. 0 (default) to display manager plus all objects. A Screen id to display manager and that Screen.

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 already initialized, this method closes it and reopens with new parameters.

Parameters

eAF	Audio frequency. Check ::eAudioFreq enum for details.
eAS	Audio sampling. Check ::eAudioSample enum for details.
eAM	Audio mode. Check ::eAudioMode enum for details.

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

eAF	::eAudioFreq enum pointer filled in with audio frequency. If nullptr (default), this value is not retrieved.
eAS	::eAudioSample enum pointer filled in with audio sampling. If nullptr (default), this value is not retrieved.
eAM	::eAudioMode enum pointer filled in with audio mode. If nullptr (default), this value is not retrieved.

Returns: 0 on success (audio output is enabled) or -1 when audio output is disabled.

◆ audioClose()

Sint32 CRM64Pro::ConfigMgr::audioClose ( )

Close the audio system.

Recommended to call at the very end of your application, after closing all resources and before Main::Terminate(). If not called, it will be automatically called on Main::Terminate().

Warning: When closing the audio system, all loaded music is also cleaned up. If your application continues, you must reload music 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

eCAD	audio driver. Check ::eConfigAudioDriver enum for further information.

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

Note: Once audio is initialized, this method has no effect.

◆ audioGetDriver()

eConfigAudioDriver CRM64Pro::ConfigMgr::audioGetDriver ( ) const

Get the audio driver.

Returns the audio driver set by default or by audioSetDriver() method. Note that it could differ from the driver in use. Use audioGetDriverInUse() to get the actual driver.

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

◆ audioGetDriverInUse()

const char * CRM64Pro::ConfigMgr::audioGetDriverInUse ( ) const

Get the audio driver name in use.

Returns the audio driver name in use (e.g., "wasapi", "directsound", "pulseaudio"). The audio must be initialized.

Returns: The driver name string or nullptr on failure/not initialized.

◆ audioSetMasterGain()

Sint32 CRM64Pro::ConfigMgr::audioSetMasterGain ( float fGain )

Set Master gain (Volume).

Sets the global volume for the mixer device.

Parameters

fGain Volume float (0.0f to 2.0f). 1.0f is nominal.

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

◆ audioGetMasterGain()

float CRM64Pro::ConfigMgr::audioGetMasterGain ( ) const

Get Master gain (Volume).

Returns: the global volume for all the tracks (0.0f - 2.0f).

◆ audioSetTagGain()

Sint32 CRM64Pro::ConfigMgr::audioSetTagGain	(	eAudioTrackTag	eTag,
		float	fGain )

Set Gain (Volume) for a specific audio track tag category.

Updates the stored volume for the tag category and immediately updates all active tracks of that type.

Parameters

eTag	The tag category to update (Music, SFX, etc).
fGain	Volume (0.0f - 2.0f). 1.0f is nominal.

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

◆ audioGetTagGain()

float CRM64Pro::ConfigMgr::audioGetTagGain ( eAudioTrackTag eTag ) const

Get the current gain for a specific audio track tag category.

Retrieves the stored volume multiplier for the given tag.

Parameters

eTag	The tag category to query (Music, SFX, etc).

Returns: The gain value for the given tag (0.0f - 2.0f).

◆ audioGetMixer()

MIX_Mixer * CRM64Pro::ConfigMgr::audioGetMixer ( ) const

Get the internal SDL3 Mixer Device handle.

Returns the raw pointer to the initialized MIX_Mixer device. This is primarily used internally by AudioTrackMgr to create tracks.

Returns: A pointer to the active MIX_Mixer, or nullptr if audio is not initialized.

◆ create()

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

Create a new screen.

Parameters

sName	the name to give to the screen object (e.g. 'myScreen'). The object name must be unique with a maximum of 64 characters or will be truncated.
iUnused	unused for the time being.

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

Note: Once created, the screen is ready to be modified and eventually shown using Screen::show().

◆ close()

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

Close and destroy a screen.

Parameters

idScreen 0 for closing all screens or the Screen id. This removes the screen and all associated resources (SDL window, SDL renderer, etc.). Additionally, it informs ImageMgr 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 when the GDK terminates.

◆ getNum()

Sint32 CRM64Pro::ConfigMgr::getNum ( ) const

Get number of loaded objects.

Returns: Number of screen objects.

◆ setName()

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

Change the object name.

Parameters

idScreen	Screen id.
sName	the name to give to the screen object (e.g. 'myScreen'). The object name must be unique with a maximum 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

iMode 0 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 handle.

Parameters

idScreen Screen id. By default, selects the default screen.

Returns: nullptr if 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

wScreen SDL_Window pointer.

Returns: nullptr if no screen with that SDL_Window is found, otherwise a valid pointer to the screen object.

◆ save()

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

Save current audio/screens configuration.

Parameters

sConfigXML	string containing the [directory]+filename+[extension] of the config XML file. Directory separators '\' and '/' are supported.
sCDC	string containing the [directory]+filename+[extension] of a CDC file where the config XML will be saved. Optional.

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

◆ load()

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

Load audio/screen configuration.

Parameters

sConfigXML	string containing the [directory]+filename+[extension] of the config XML file. Directory separators '\' and '/' are supported.
sCDC	string containing the [directory]+filename+[extension] of a CDC file that contains the config XML file. Optional.

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

Note: If audio or 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 configuring audio/screen settings.

Parameters

sConfigXML	string containing the name of the config XML file.
idConfigCDC	id of an open CDC file that contains the config XML and custom setup XML files. Using id instead of CDC name allows opening secured CDC files.
sCustomSetupXML	string containing the name of the custom setup XML file. Optional.

Returns: 0 when configuration is saved or exited with OK, or a negative value when no configuration saved or exit button clicked.

Note: By default, 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 configuring audio/screen settings.

Parameters

sConfigXML	string containing the name of the config XML file.
sConfigCDC	string containing the [directory]+filename+[extension] of a CDC file that contains the config and custom setup XML files. Directory separators '\' and '/' are supported.
sCustomSetupXML	string containing the name of the custom setup XML file. Optional.

Returns: 0 when configuration is saved or exited with OK, or a negative value when no configuration saved or exit button clicked.

Note: By default, uses a built-in layout.

Description

Overview

Key features

Configuration areas

Default configuration

Manager type

Best practices

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ eConfigAudioDriver

◆ eAudioFreq

◆ eAudioSample

◆ eAudioMode

◆ eConfigRendererDriver

◆ eConfigScreenMode

Function Documentation

◆ info() [1/2]

◆ getName()

◆ getID()

◆ show()

◆ hide()

◆ status()

◆ setIcon()

◆ setDriver()

◆ getDriver()

◆ getDriverInUse()

◆ setVSync()

◆ getVSync()

◆ setMode()

◆ getMode()

◆ setSize()

◆ getSize()

◆ setLogicalPresentation()

◆ getLogicalPresentation()

◆ setPosition()

◆ getPosition()

◆ setClipRect()

◆ getClipRect()

◆ setTitle()

◆ getTitle()

◆ setBorder()

◆ getBorder()

◆ getWindow()

◆ getRenderer()

◆ getSnapshot() [1/2]

◆ getSnapshot() [2/2]

◆ clear()

◆ setRenderCallback()

◆ fadeToColor()

◆ fadeToImage()

◆ info() [2/2]

◆ audioInit()

◆ audioStatus()

◆ audioClose()

◆ audioSetDriver()

◆ audioGetDriver()

◆ audioGetDriverInUse()

◆ audioSetMasterGain()

◆ audioGetMasterGain()

◆ audioSetTagGain()

◆ audioGetTagGain()

◆ audioGetMixer()

◆ create()

◆ close()

◆ getNum()

◆ setName()

◆ reset()

◆ get() [1/2]

◆ get() [2/2]

◆ save()

◆ load()

◆ setup() [1/2]

◆ setup() [2/2]