Detailed Description

Screen Object class.

Public Member Functions
bool	info (Sint32 iMode=0) override
	Request screen object information.
const string &	getName () const override
	Get the name.
Uint32	getID () const override
	Get the ID.
bool	show ()
	Show the screen.
bool	hide ()
	Hide the screen.
Sint32	status () const
	Get the screen status.
bool	setIcon (SDL_Surface *suIcon)
	Set an icon.
bool	setDriver (eConfigRendererDriver eCRD)
	Set the renderer driver.
eConfigRendererDriver	getDriver () const
	Get the renderer driver.
eConfigRendererDriver	getDriverInUse () const
	Get the renderer driver in use.
bool	setVSync (bool bEnabled)
	Set the VSync mode.
bool	getVSync () const
	Get current VSync mode.
bool	setMode (eConfigScreenMode eCSM)
	Set the screen mode.
eConfigScreenMode	getMode () const
	Get the screen mode.
bool	setSize (Sint32 iWidth, Sint32 iHeight)
	Set the size of the screen.
Sint32	getWidth () const
	Get the screen width.
Sint32	getHeight () const
	Get the screen height.
bool	setLogicalPresentation (Sint32 iWidth, Sint32 iHeight, SDL_RendererLogicalPresentation eSDL_RLP=SDL_LOGICAL_PRESENTATION_DISABLED)
	Set the logical presentation size of the screen.
bool	getLogicalPresentation (Sint32 iWidth=nullptr, Sint32 iHeight=nullptr, SDL_RendererLogicalPresentation *eSDL_RLP=nullptr) const
	Get the logical presentation size of the screen.
bool	setPosition (Sint32 iX, Sint32 iY)
	Set the position.
Sint32	getX () const
	Get the screen X position.
Sint32	getY () const
	Get the screen Y position.
bool	setClipRect (SDL_Rect *rClip)
	Set clipping rect.
bool	getClipRect (SDL_Rect *rClip)
	Get clipping rect.
bool	isClipRectEnabled () const
	Check if clipping rect is enabled.
bool	setTitle (const string &sName)
	Set the title.
const string &	getTitle () const
	Get the title.
bool	setBorder (bool bEnabled)
	Set the border for the screen.
bool	getBorder () const
	Get the border for the screen.
SDL_Window *	getWindow ()
	Get the SDL_Window associated to this screen.
SDL_Renderer *	getRenderer ()
	Get the SDL_Renderer associated to this screen.
SDL_Surface *	getSnapshot ()
	Get a SDL_Surface with a screen snapshot.
bool	getSnapshot (const string &sFile)
	Save the screen snapshot to an external PNG file.
bool	clear (Uint8 iR=0, Uint8 iG=0, Uint8 iB=0, Uint8 iA=255)
	Clear the screen.
bool	setRenderCallback (Sint32(myRenderFunc)(Sint32 iMode, void pObj), void *pObj=nullptr)
	Set a callback function for rendering your graphics at Render Frame Rate.
bool	fadeToColor (Uint8 iR, Uint8 iG, Uint8 iB, Sint32 iTime, SDL_FRect *rDst=nullptr)
	Perform a fade effect of this screen to the given color.
bool	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.

Member Function Documentation

◆ info()

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

override

Request screen object information.

Writes screen information to the default log.

Parameters

iMode unused for the time being.

Returns: true on success or false on failure.

◆ getName()

const string & CRM64Pro::Screen::getName ( ) const

override

Get the name.

Returns: The object name.

◆ getID()

Uint32 CRM64Pro::Screen::getID ( ) const

override

Get the ID.

Returns: Object ID.

◆ show()

bool 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: true on success or false on failure.

◆ hide()

bool 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: true on success or false on failure.

◆ status()

Sint32 CRM64Pro::Screen::status ( ) const

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

bool 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: true on success, or false on failure.

◆ setDriver()

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

Set the renderer driver.

Parameters

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

Returns: true on success or false on failure.

Note: If the screen was already initialized, it will be destroyed and re-created with the new driver. All associated resources (textures) will be lost/recreated.; If the screen was not initialized, this method will just set the desired driver for the next initialization.

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

bool CRM64Pro::Screen::setVSync ( bool bEnabled )

Set the VSync mode.

Parameters

bEnabled false to disable, true to enable. Common monitor refresh rates are 60, 70, 75, 120 or 155.

Returns: true on success or false on failure.

◆ getVSync()

bool CRM64Pro::Screen::getVSync ( ) const

Get current VSync mode.

Returns: false if VSync is disabled, true if it is enabled.

◆ setMode()

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

Set the screen mode.

Parameters

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

Returns: true on success or false 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()

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

Set the size of the screen.

Parameters

iWidth	screen width.
iHeight	screen height.

Returns: true on success or false on failure.

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

◆ getWidth()

Sint32 CRM64Pro::Screen::getWidth ( ) const

Get the screen width.

Returns: The screen width in pixels.

◆ getHeight()

Sint32 CRM64Pro::Screen::getHeight ( ) const

Get the screen height.

Returns: The screen height in pixels.

◆ setLogicalPresentation()

bool 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: true on success or false on failure.

◆ getLogicalPresentation()

bool 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: true on success, or false on failure.

◆ setPosition()

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

Set the position.

Parameters

iX	screen X position.
iY	screen Y position.

Returns: true on success or false on failure.

◆ getX()

Sint32 CRM64Pro::Screen::getX ( ) const

Get the screen X position.

Returns: The screen X position in pixels.

◆ getY()

Sint32 CRM64Pro::Screen::getY ( ) const

Get the screen Y position.

Returns: The screen Y position in pixels.

◆ setClipRect()

bool 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: true on success or false on failure.

◆ getClipRect()

bool 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: true if clipping is enabled, or false if clipping is disabled.

See also: isClipRectEnabled()

◆ isClipRectEnabled()

bool CRM64Pro::Screen::isClipRectEnabled ( ) const

Check if clipping rect is enabled.

Returns: true if clipping is enabled, false if it is disabled.

◆ setTitle()

bool 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: true on success or false on failure.

◆ getTitle()

const string & CRM64Pro::Screen::getTitle ( ) const

Get the title.

Returns: The window title.

◆ setBorder()

bool CRM64Pro::Screen::setBorder ( bool bEnabled )

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

bEnabled false for disabling and true for enabling it.

Returns: true on success or false on failure.

◆ getBorder()

bool CRM64Pro::Screen::getBorder ( ) const

Get the border for the screen.

Returns: false if the border is disabled, true 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]

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

Save the screen snapshot to an external PNG file.

Parameters

sFile string containing the [directory]+filename+[extension].

Returns: true on success or false on failure.

Note: Getting a screen snapshot is quite slow.

◆ clear()

bool 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: true on success or false on failure.

◆ setRenderCallback()

bool 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: true on success or false 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()

bool 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: true on success or false on failure.

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

◆ fadeToImage()

bool 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: true on success or false on failure.

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

Detailed Description

Public Member Functions

Member Function Documentation

◆ info()

◆ getName()

◆ getID()

◆ show()

◆ hide()

◆ status()

◆ setIcon()

◆ setDriver()

◆ getDriver()

◆ getDriverInUse()

◆ setVSync()

◆ getVSync()

◆ setMode()

◆ getMode()

◆ setSize()

◆ getWidth()

◆ getHeight()

◆ setLogicalPresentation()

◆ getLogicalPresentation()

◆ setPosition()

◆ getX()

◆ getY()

◆ setClipRect()

◆ getClipRect()

◆ isClipRectEnabled()

◆ setTitle()

◆ getTitle()

◆ setBorder()

◆ getBorder()

◆ getWindow()

◆ getRenderer()

◆ getSnapshot() [1/2]

◆ getSnapshot() [2/2]

◆ clear()

◆ setRenderCallback()

◆ fadeToColor()

◆ fadeToImage()