Detailed Description

v4.10 (18 February 2024)
The Config module includes the Config Manager and Screen for handling general, audio and video configuration settings of the GDK.

Control settings:

General: modify the behaviour of some general seetings (check ConfigMgr::iMTFriendly).
Audio: enables or disables the Audio system and configures its attributes.
Video: add, modify and release "screens". A screen is a top-level entity that contains a SDL_Window, a SDL_Renderer plus all its attributes.

ConfigMgr automatically uses below default configuration:

Default screen with:
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)
Driver:	CRD_DEFAULT (use default renderer driver)
Batching:	1 (enabled)
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

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_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_DIRECT3D = 4 , CRM64Pro::CRD_DIRECT3D11 = 5 , CRM64Pro::CRD_DIRECT3D12 = 6 , CRM64Pro::CRD_X11 = 7 , 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 ()
	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::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::setLogicalPresentation (Sint32 iWidth, Sint32 iHeight, SDL_RendererLogicalPresentation eSDL_RLP=SDL_LOGICAL_PRESENTATION_DISABLED, SDL_ScaleMode eSDL_SM=SDL_SCALEMODE_NEAREST)
	Set the logical presentation size of the screen.

Sint32	CRM64Pro::Screen::getLogicalPresentation (Sint32 iWidth=nullptr, Sint32 iHeight=nullptr, SDL_RendererLogicalPresentation eSDL_RLP=nullptr, SDL_ScaleMode eSDL_SM=nullptr)
	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 ()
	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.

Screen *	CRM64Pro::ConfigMgr::get (Sint32 idScreen=0)
	Get a pointer to the screen using its handler.

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

enum CRM64Pro::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 audio frequency can be modified, other values are set to the maximum quality of the output device. Only for Win32/Win64.
CAD_DIRECTSOUND	Used in Config::audioSetDriver(), uses DirectSound driver. Audio settings can be modified. Only for Win32/Win64.
CAD_ERROR	Returned by Config::audioGetDriver() if the method call failed.

◆ eAudioFreq

enum CRM64Pro::eAudioFreq

Audio frequency.

Enumerator
AF_DEFAULT	Default value.
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 value.
AS_8	8bits samples output.
AS_16	16bits samples output.
AS_32	32bits floating point samples output.

◆ eAudioMode

enum CRM64Pro::eAudioMode

Audio mode.

Enumerator
AM_DEFAULT	Default value.
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	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_DIRECT3D12	Used in Screen::setDriver(), uses Direct3D v12 renderer driver. Only for Win64 (needs Windows 10+).
CRD_X11	Used in Screen::setDriver(), uses X11 renderer driver. Only for Linux.
CRD_ERROR	Returned by Screen::getDriver() in case of error.

◆ eConfigScreenMode

enum CRM64Pro::eConfigScreenMode

Screen modes.

Enumerator
CSM_WINDOW	Used in Screen::setMode(), uses a windowed mode (default value).
CSM_FULLSCREEN	Used in Screen::setMode(), uses a fullscreen window mode which takes the size of the desktop. Recommended fullscreen mode.
CSM_FULLSCREENEXCLUSIVE	Used in Screen::setMode(), uses an exclusive fullscreen mode which changes the monitor video mode to the closest mode for matching given resolution.

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

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 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_DISABLED	screen is uninitialized.
C64_STATUS_HIDDEN	screen is initialized but hidden.
C64_STATUS_SHOWN	screen 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

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 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().
Recreate the screen (window and renderer)

◆ 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

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

◆ setMode()

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

Set the screen mode.

Parameters

eCSM	screen 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().
Recreate the screen (window and renderer)
When entering into a fullscreen mode, if the resolution is different from the application's size and no logical presention mode is set, a logical presentation mode is is automatically set.
When entering into window mode, if resolution and logical size match, the presention mode is disabled.

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

Parameters

iWidth	screen width.
iHeight	screen height.

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

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

◆ 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

iWidth	an integer pointer filled in with screen width. If nullptr is passed, the method ignores the retrieving of this value.
iHeight	an 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.

◆ setLogicalPresentation()

Sint32 CRM64Pro::Screen::setLogicalPresentation	(	Sint32	iWidth,
		Sint32	iHeight,
		SDL_RendererLogicalPresentation	eSDL_RLP = `SDL_LOGICAL_PRESENTATION_DISABLED`,
		SDL_ScaleMode	eSDL_SM = `SDL_SCALEMODE_NEAREST`
	)

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.
eSDL_SM	set the logical presentation quality: SDL_SCALEMODE_NEAREST for nearest pixel sampling or SDL_SCALEMODE_LINEAR for linear filtering. By default, it is set to SDL_SCALEMODE_NEAREST.

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`,
		SDL_ScaleMode *	eSDL_SM = `nullptr`
	)

Get the logical presentation size of the screen.

This method return the size of the logical presentation size, mode and quality for this screen.

Parameters

iWidth	an integer pointer filled in with logical presentation width. If nullptr is passed, the method ignores the retrieving of this value.
iHeight	an integer pointer filled in with logical presentation height. If nullptr is passed, the method ignores the retrieving of this value.
eSDL_RLP	a SDL_RendererLogicalPresentation enum pointer that will be filled in with the logical presentation mode. If nullptr is passed, the method ignores the retrieving of this value.
eSDL_SM	a enum pointer to the logical presentation quality: SDL_SCALEMODE_NEAREST for nearest pixel sampling or SDL_SCALEMODE_LINEAR for linear filtering. 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

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.

This method return the position of a screen.

Parameters

iX	a pointer filled in with screen X position. If nullptr is passed, the method ignores the retrieving of this value.
iY	a 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

rClip pointer 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

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

Returns: 1 if clip is enabled, 0 if clip is disabled 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

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

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

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

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()(Sint32 iMode, void pObj)	myRenderFunc,
		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 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.
pObj	pointer 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

iR	The red color value.
iG	The green color value.
iB	The blue color value.
iTime	duration in milliseconds for performing the effect. Minimum of 50ms and maximum of 10000ms.
rDst	the 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

idImage	Image handler
iTime	duration in milliseconds for performing the effect. Minimum of 50ms and maximum of 10000ms.
rDst	the destination SDL_Rect structure or nullptr for using the whole screen size. By default, it is set to nullptr.
rSrc	the 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

eAF	Audio frequency. Check eAudioFreq enum for further information.
eAS	Audio sampling. Check eAudioSample enum for further information.
eAM	Audio 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

eAF	eAudioFreq enum pointer filled in with audio frequency. If nullptr is passed (value by default), the method ignores the retrieving of this value.
eAS	eAudioSample enum pointer filled in with audio sampling. If nullptr is passed (value by default), the method ignores the retrieving of this value.
eAM	eAudioMode 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

eCAD	audio 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

iVolume volume 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

iVolume volume 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

iNum	number 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_func	function pointer.
arg	pointer 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

sName	The 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.
iUnused	unused 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

idScreen 0 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

idScreen	Screen id.
sName	The 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

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

Parameters

idScreen Screen 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

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

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

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

sConfigXML	string containing the name of the config XML file.
idConfigCDC	id 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.
sCustomSetupXML	string containing the name of the custom setup XML file. This parameter is optional.

Returns: 0 on when configuration is saved and clicked on OK or a negative value when no configuration saved or clicked exit button.

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

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 the custom setup XML files. Directory separators '\' and '/' are supported.
sCustomSetupXML	string containing the name of the custom setup XML file. This parameter is optional.

Returns: 0 on when configuration is saved and clicked on OK or a negative value when no configuration saved or clicked exit button.

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

Detailed Description

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

◆ audioMusicVolume()

◆ audioSoundVolume()

◆ audioMixingChannels()

◆ audioHook()

◆ create()

◆ close()

◆ getNum()

◆ setName()

◆ reset()

◆ get() [1/2]

◆ get() [2/2]

◆ save()

◆ load()

◆ setup() [1/2]

◆ setup() [2/2]