| CRM64Pro GDK v0.18.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Config
Core modules

## Description

Configuration Manager and Screen objects for general, audio and video settings [v26.01.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::setMTFriendly())
- 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

setMTFriendly() | 0 (disabled)

Audio settings

Audio.bInit | false (disabled)
Audio.iDriver | 0 (use default audio driver)
Audio.eAS | CAS_16 (16 bit sampling)
Audio.eAF | CAF_22K (22050Hz)
Audio.eAM | CAM_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 x 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::configMgr()

Note
  The Configuration Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::configMgr() 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 : Sint32 { CRM64Pro::CAD_DEFAULT = 0 , CRM64Pro::CAD_WASAPI = 1 , CRM64Pro::CAD_DIRECTSOUND = 2 , CRM64Pro::CAD_ERROR = -1 }
| Audio drivers. More...
enum | CRM64Pro::eConfigAudioFreq : Sint32 { CRM64Pro::CAF_DEFAULT = 0 , CRM64Pro::CAF_22K = 22050 , CRM64Pro::CAF_44K = 44100 , CRM64Pro::CAF_48K = 48000 }
| Audio frequency. More...
enum | CRM64Pro::eConfigAudioSample : Sint32 { CRM64Pro::CAS_DEFAULT = 0 , CRM64Pro::CAS_8 = SDL_AUDIO_U8 , CRM64Pro::CAS_16 = SDL_AUDIO_S16 , CRM64Pro::CAS_32 = SDL_AUDIO_F32 }
| Audio sample format. More...
enum | CRM64Pro::eConfigAudioMode : Sint32 { CRM64Pro::CAM_DEFAULT = 0 , CRM64Pro::CAM_MONO = 1 , CRM64Pro::CAM_STEREO = 2 , CRM64Pro::CAM_SURROUND21 = 3 , CRM64Pro::CAM_QUAD = 4 , CRM64Pro::CAM_SURROUND41 = 5 , CRM64Pro::CAM_SURROUND51 = 6 , CRM64Pro::CAM_SURROUND61 = 7 , CRM64Pro::CAM_SURROUND71 = 8 }
| Audio mode. More...
enum | CRM64Pro::eConfigRendererDriver : Sint32 { 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 : Sint32 { CRM64Pro::CSM_WINDOW = 0 , CRM64Pro::CSM_FULLSCREEN = 1 , CRM64Pro::CSM_FULLSCREENEXCLUSIVE = 2 }
| Screen modes. More...

## Functions
Sint32 | CRM64Pro::ConfigMgr::save (const string &sConfigXML, const string &sCDCFile="")
| Save current audio/screens configuration.
Sint32 | CRM64Pro::ConfigMgr::loadFromFile (const string &sConfigXML)
| Load audio/screen configuration from a file.
Sint32 | CRM64Pro::ConfigMgr::load (const string &sCDCFile, const string &sConfigXML)
| Load audio/screen configuration from a CDC file.
Sint32 | CRM64Pro::ConfigMgr::load (Sint32 idCDC, const string &sConfigXML)
| Load audio/screen configuration from a CDC file.
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 : Sint32

Audio drivers.

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

## ◆ eConfigAudioFreq

enum CRM64Pro::eConfigAudioFreq : Sint32

Audio frequency.

Enumerator
CAF_DEFAULT | Engine default sample rate; resolves to ::CAF_44K (44100 Hz).
CAF_22K | 22050 Hz output.
CAF_44K | 44100 Hz output; CD audio sample rate.
CAF_48K | 48000 Hz output; broadcast/professional sample rate.

## ◆ eConfigAudioSample

enum CRM64Pro::eConfigAudioSample : Sint32

Audio sample format.

Enumerator
CAS_DEFAULT | Engine default sample format; resolves to ::CAS_16.
CAS_8 | 8-bit samples.
CAS_16 | 16-bit samples.
CAS_32 | 32-bit floating-point samples.

## ◆ eConfigAudioMode

enum CRM64Pro::eConfigAudioMode : Sint32

Audio mode.

Enumerator
CAM_DEFAULT | Default mode.
CAM_MONO | Mono output.
CAM_STEREO | Stereo output.
CAM_SURROUND21 | Surround 2.1 output.
CAM_QUAD | Quad output.
CAM_SURROUND41 | Surround 4.1 output.
CAM_SURROUND51 | Surround 5.1 output.
CAM_SURROUND61 | Surround 6.1 output.
CAM_SURROUND71 | Surround 7.1 output.

## ◆ eConfigRendererDriver

enum CRM64Pro::eConfigRendererDriver : Sint32

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 : Sint32

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

## ◆ save()

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

Save current audio/screens configuration.

Parameters

  sConfigXML | string containing the [directory]+filename+[extension] of the config XML file. Directory separators '\' and '/' are supported.
  sCDCFile | 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.

## ◆ loadFromFile()

Sint32 CRM64Pro::ConfigMgr::loadFromFile | ( | const string & | sConfigXML | ) |

Load audio/screen configuration from a file.

Parameters

  sConfigXML | string containing the [directory]+filename+[extension] of the config XML file. Directory separators '\' and '/' are supported.

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.

## ◆ load() [1/2]

Sint32 CRM64Pro::ConfigMgr::load | ( | const string & | sCDCFile,
|  | const string & | sConfigXML )

Load audio/screen configuration from a CDC file.

Parameters

  sCDCFile | string containing the [directory]+filename+[extension] of a CDC file that contains the config XML file.
  sConfigXML | string containing the name of the config XML file.

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.

## ◆ load() [2/2]

Sint32 CRM64Pro::ConfigMgr::load | ( | Sint32 | idCDC,
|  | const string & | sConfigXML )

Load audio/screen configuration from a CDC file.

Parameters

  idCDC | CDC id of an open CDC file that contains the config XML file.
  sConfigXML | string containing the name of the config XML file.

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 on success, or a negative error code on failure or cancel.

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 on success, or a negative error code on failure or cancel.

Note
  By default, uses a built-in layout.