Description

To display dialogs atop the game graphics, backends must provide an overlay mode.

The overlay is currently forced at 16 bpp.

For 'coolness' we usually want to have an overlay that is blended over the game graphics. On backends that support alpha blending, this is no issue but on other systems this needs some trickery.

Essentially, we fake (alpha) blending on these systems by copying the current game graphics into the overlay buffer when activating the overlay, and then manually compose whatever graphics we want to show in the overlay. This works because we assume the game to be "paused" whenever an overlay is active.

Parameters

inGame Whether the overlay is used to display GUI or in game images

Functions
virtual void	OSystem::showOverlay (bool inGUI=true)=0

virtual void	OSystem::hideOverlay ()=0

virtual bool	OSystem::isOverlayVisible () const =0

virtual Graphics::PixelFormat	OSystem::getOverlayFormat () const =0

virtual void	OSystem::clearOverlay ()=0

virtual void	OSystem::grabOverlay (Graphics::Surface &surface)=0

virtual void	OSystem::copyRectToOverlay (const void *buf, int pitch, int x, int y, int w, int h)=0

virtual int16	OSystem::getOverlayHeight ()=0

virtual int16	OSystem::getOverlayWidth ()=0

Function Documentation

◆ showOverlay()

virtual void OSystem::showOverlay ( bool inGUI = true )

pure virtual

Activate the overlay mode.

Implemented in OSystem_Wii, OSystem_N64, OSystem_Dreamcast, N3DS::OSystem_3DS, OSystem_DS, ModularGraphicsBackend, and OSystem_PSP.

◆ hideOverlay()

virtual void OSystem::hideOverlay ( )

pure virtual

Deactivate the overlay mode.

Implemented in OSystem_Wii, OSystem_N64, OSystem_Dreamcast, N3DS::OSystem_3DS, OSystem_DS, ModularGraphicsBackend, and OSystem_PSP.

◆ isOverlayVisible()

virtual bool OSystem::isOverlayVisible ( ) const

pure virtual

Return true if the overlay mode is activated, false otherwise.

Implemented in OSystem_Wii, OSystem_N64, N3DS::OSystem_3DS, OSystem_Dreamcast, OSystem_DS, ModularGraphicsBackend, and OSystem_PSP.

◆ getOverlayFormat()

virtual Graphics::PixelFormat OSystem::getOverlayFormat ( ) const

pure virtual

Return the pixel format description of the overlay.

See also: Graphics::PixelFormat

Implemented in OSystem_Wii, OSystem_N64, OSystem_Dreamcast, N3DS::OSystem_3DS, OSystem_DS, OSystem_PSP, and ModularGraphicsBackend.

◆ clearOverlay()

virtual void OSystem::clearOverlay ( )

pure virtual

Reset the overlay.

After calling this method while the overlay mode is active, the user should be seeing only the game graphics. How this is achieved depends on how the backend implements the overlay. It either sets all pixels of the overlay to be transparent (when alpha blending is used) or, in case of fake alpha blending, it might just put a copy of the current game graphics screen into the overlay.

Implemented in OSystem_Wii, OSystem_N64, N3DS::OSystem_3DS, OSystem_Dreamcast, OSystem_DS, ModularGraphicsBackend, and OSystem_PSP.

◆ grabOverlay()

virtual void OSystem::grabOverlay ( Graphics::Surface & surface )

pure virtual

Copy the content of the overlay into a surface provided by the caller.

This is only used to implement fake alpha blending.

Implemented in OSystem_Wii, OSystem_N64, N3DS::OSystem_3DS, OSystem_Dreamcast, OSystem_DS, ModularGraphicsBackend, and OSystem_PSP.

◆ copyRectToOverlay()

virtual void OSystem::copyRectToOverlay	(	const void *	buf,
		int	pitch,
		int	x,
		int	y,
		int	w,
		int	h
	)

pure virtual

Blit a graphics buffer to the overlay.

In a sense, this is the reverse of grabOverlay.

Parameters

buf	Buffer containing the graphics data source.
pitch	Pitch of the buffer (number of bytes in a scanline).
x	x coordinate of the destination rectangle.
y	y coordinate of the destination rectangle.
w	Width of the destination rectangle.
h	Height of the destination rectangle.