Description

A dekstop interface based on SDL2 (see Desktop Interface module).

NOTE:

    -Must be linked against SDL2 and SDL2-image libraries.
    -It is not thread-safe.
    -This implementation of the graphics interface won't work correctly
    if the methods that deal with the video are executed outside the
    main thread.

Copyright: See LICENSE.txt and AUTHORS.txt file.

http://jafma.net

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Collaboration diagram for Desktop Interface on SDL2:

Classes
class	DesktopSDL2
	The desktop interface main class, based on SDL2 and SDL2-image. More...

class	PalWinSDL2
	A palettized window managed by SDL2. More...

Class Documentation

◆ DesktopSDL2

class DesktopSDL2

The desktop interface main class, based on SDL2 and SDL2-image.

Definition at line 53 of file DesktopSDL2.h.

Inheritance diagram for DesktopSDL2:

[legend]

Collaboration diagram for DesktopSDL2:

[legend]

Static Public Member Functions
static DesktopSDL2 &	theDesktop (const SoundPlayerParms &spps)
	Get the singleton desktop interface with SPPS (created in the 1st call) More...

Static Public Member Functions inherited from DesktopInterface
static bool	keyIsNumber (KeyID kid) noexcept
	< Return TRUE if the given KEY is a number. More...

static bool	keyIsLetter (KeyID kid) noexcept
	< Return TRUE if the given KEY is a letter. More...

static bool	keyIsFunction (KeyID kid) noexcept
	< Return TRUE if the given KEY is a function key. More...

static bool	keyIsForMotion (KeyID kid) noexcept
	< Return TRUE if the key can be used for moving things on the screen. More...

Public Member Functions
-----------------— Constructors -------------------------—
(Constructors and destructors are private)
	DesktopSDL2 (const DesktopSDL2 &)=delete
	Copies forbidden.

DesktopSDL2 &	operator= (const DesktopSDL2 &)=delete
	Assignments forbidden.

	DesktopSDL2 (DesktopSDL2 &&)=delete
	Moves forbidden.

DesktopSDL2 &	operator= (DesktopSDL2 &&)=delete
	Assignment-moves forbidden.

virtual	~DesktopSDL2 (void)
	Destructor: finish both libraries.

-----------------— Image file methods --------------------—
RGBImage	readPNGImageFile (const std::string &filepath)
	Read a PNG image from file and return it as an RGBImage. More...

void	writePNGImageFile (const RGBImage &img, const std::string &filepath)
	Write an RGBImage into a PNG image in the given file. More...

-----------------— Graphics methods ----------------------—
PalettizedWindow *	createWindow (const std::string &title, unsigned dimw, unsigned dimh, unsigned scalex, unsigned scaley)
	Factory method: return a new palettized window of type PalWinSDL2. More...

void	getDesktopResolution (unsigned &w, unsigned &h)
	Fill W and H with the current desktop resolution in pixels. More...

-----------------— Sound methods -----------------------—
void	playSound (double secs, const SoundMonoProducer &waveprod, bool async)
	Start playing the sound produced by WAVEPROD for the next SECS seconds. More...

void	pausePlaying (void)
	Pause the current playing, if any, and play just silence. More...

void	resumePlaying (void)
	Resume a previously paused playing. More...

bool	playingPaused (void)
	Return whether there is a paused playing or not. More...

bool	soundPlaying (void) const noexcept
	Return TRUE if the last commanded sound is still playing. More...

void	nextSoundPlayingTime (double &t) noexcept
	Update T with the next time where the sound callback will be called. More...

const SoundMonoProducer &	lastSoundProducer (void) const
	Get the current sound producer or raise an exception if none. More...

double	lastSoundDuration (void) const noexcept
	Get the current sound duration. More...

-----------------— Keyboard methods ----------------------—
void	enableTextEvents (void)
	Enable K_TEXT events from now on to the active window in the desktop. More...

void	disableTextEvents (void)
	Disable K_TEXT events from now on to the active window in the desktop. More...

bool	textEventsEnabled (void) const
	Enable K_TEXT events from now on to the active window in the desktop. More...

-----------------— Clipboard methods ---------------------—
std::string	copyFromClipboard (void) const
	Return a copy of the text existing in the clipboard, if any. More...

void	copyToClipboard (const std::string &txt) const
	Copy TXT, if not empty, to the clipboard. More...

Public Member Functions inherited from DesktopInterface
virtual	~DesktopInterface (void)=default

	DesktopInterface (const DesktopInterface &)=delete

DesktopInterface &	operator= (const DesktopInterface &)=delete

	DesktopInterface (const DesktopInterface &&)=delete

DesktopInterface &	operator= (const DesktopInterface &&)=delete

const SoundPlayerParms &	playerParms (void) const noexcept
	< Must return the current parameters of the sound player system. More...

Additional Inherited Members
Public Types inherited from DesktopInterface
enum	KeyID { K_ESC =0 , K_F1 , K_F2 , K_F3 , K_F4 , K_F5 , K_F6 , K_F7 , K_F8 , K_F9 , K_F10 , K_F11 , K_F12 , K_1 , K_2 , K_3 , K_4 , K_5 , K_6 , K_7 , K_8 , K_9 , K_0 , K_BACK , K_DEL , K_TAB , K_BEGIN , K_END , K_PGUP , K_PGDOWN , K_Q , K_W , K_E , K_R , K_T , K_Y , K_U , K_I , K_O , K_P , K_ENTER , K_CAPSLOCK , K_A , K_S , K_D , K_F , K_G , K_H , K_J , K_K , K_L , K_CAPSLEFT , K_Z , K_X , K_C , K_V , K_B , K_N , K_M , K_COMMA , K_PERIOD , K_CAPSRIGHT , K_CTRLLEFT , K_ALTLEFT , K_SPACE , K_ALTRIGHT , K_CTRLRIGHT , K_LEFT , K_DOWN , K_UP , K_RIGHT , K_MINUS , K_PLUS , K_DIV , K_MULT , K_BSLASH , K_UNDERS , K_SQUBRO , K_SQUBRC , K_CURBRO , K_CURBRC , K_EXCL , K_DQUOTE , K_AT , K_SHARP , K_DOLLAR , K_PERC , K_AMPER , K_PARO , K_PARC , K_EQUAL , K_QUEST , K_VERT , K_CIRC , K_APOST , K_LESS , K_GREAT , K_SEMIC , K_COLON , NUM_OF_KEY_IDS }
	IDs for the most common keys in a keyboard. More...

typedef std::function< double(double t, uint64_t i, unsigned l, unsigned pos)>	SoundMonoProducer
	A routine to produce a mono-channel sound wave. More...

Static Public Attributes inherited from DesktopInterface
static const std::vector< std::string >	KeyNames
	Key names. More...

static const SoundMonoProducer	SilenceMonoProducer
	Pre-defined sound producing routine that generates silence all time. More...

Protected Member Functions inherited from DesktopInterface
	DesktopInterface (const SoundPlayerParms &spps)

Protected Attributes inherited from DesktopInterface
SoundPlayerParms	playerparms_

Member Function Documentation

◆ theDesktop()

static DesktopSDL2 & DesktopSDL2::theDesktop ( const SoundPlayerParms & spps )

static

Get the singleton desktop interface with SPPS (created in the 1st call)

Return the singleton interface that can be associated with the program (only one interface per executable program). SPSS is ignored in further calls.

◆ readPNGImageFile()

RGBImage DesktopSDL2::readPNGImageFile ( const std::string & filepath )

virtual

Read a PNG image from file and return it as an RGBImage.

Implements DesktopInterface.

◆ writePNGImageFile()

void DesktopSDL2::writePNGImageFile	(	const RGBImage &	img,
		const std::string &	filepath
	)

virtual

Write an RGBImage into a PNG image in the given file.

Implements DesktopInterface.

◆ createWindow()

PalettizedWindow * DesktopSDL2::createWindow	(	const std::string &	title,
		unsigned	dimw,
		unsigned	dimh,
		unsigned	scalex,
		unsigned	scaley
	)

virtual

Factory method: return a new palettized window of type PalWinSDL2.

Implements DesktopInterface.

◆ getDesktopResolution()

void DesktopSDL2::getDesktopResolution	(	unsigned &	w,
		unsigned &	h
	)

virtual

Fill W and H with the current desktop resolution in pixels.

Raise exception if any error.

Implements DesktopInterface.

◆ playSound()

void DesktopSDL2::playSound	(	double	secs,
		const SoundMonoProducer &	waveprod,
		bool	async
	)

virtual

Start playing the sound produced by WAVEPROD for the next SECS seconds.

The time requested from WAVEPROD will start at 0, and the index of the sample too, for the first sound value requested from that monoproducer.

Parameters

waveprod	will be called (potentially within a new thread) to get sound values. It will be copied inside this object.
secs	can be <= 0.0 to indicate a neverending sound. A new call to this method -in the async case- with a different sound starts the new sound as soon as the SDL2 internal buffer for the old sound are used.

Note: -When the desktop singleton is created, if not suitable support for sound is found, this routine will not do anything.; -If ASYNC == TRUE, the SDL2 audio system will continue to play silence until the end of the next call to playSound() that has ASYNC == FALSE. If ASYNC == FALSE, the audio system is paused after the end of that sound.; -According to SDL2 wiki, the audio callback routine runs in a separate thread in most cases.

Implements DesktopInterface.

◆ pausePlaying()

void DesktopSDL2::pausePlaying ( void )

virtual

Pause the current playing, if any, and play just silence.

Several calls to this method just pause once. If nothing is being played, this does nothing. After a call to playSound() in non-async mode, the playing is paused; this has sense only in async mode.

Implements DesktopInterface.

◆ resumePlaying()

void DesktopSDL2::resumePlaying ( void )

virtual

Resume a previously paused playing.

Several calls to this method just resume once.

Implements DesktopInterface.

◆ playingPaused()

bool DesktopSDL2::playingPaused ( void )

inlinevirtual

Return whether there is a paused playing or not.

Implements DesktopInterface.

Definition at line 146 of file DesktopSDL2.h.

◆ soundPlaying()

bool DesktopSDL2::soundPlaying ( void ) const

inlinevirtualnoexcept

Return TRUE if the last commanded sound is still playing.

Implements DesktopInterface.

Definition at line 149 of file DesktopSDL2.h.

◆ nextSoundPlayingTime()

void DesktopSDL2::nextSoundPlayingTime ( double & t )

virtualnoexcept

Update T with the next time where the sound callback will be called.

Do nothing if no sound support is available.

Implements DesktopInterface.

◆ lastSoundProducer()

const SoundMonoProducer & DesktopSDL2::lastSoundProducer ( void ) const

inlinevirtual

Get the current sound producer or raise an exception if none.

Implements DesktopInterface.

Definition at line 156 of file DesktopSDL2.h.

◆ lastSoundDuration()

double DesktopSDL2::lastSoundDuration ( void ) const

inlinevirtualnoexcept

Get the current sound duration.

Implements DesktopInterface.

Definition at line 159 of file DesktopSDL2.h.

◆ enableTextEvents()

void DesktopSDL2::enableTextEvents ( void )

virtual

Enable K_TEXT events from now on to the active window in the desktop.

Implements DesktopInterface.

◆ disableTextEvents()

void DesktopSDL2::disableTextEvents ( void )

virtual

Disable K_TEXT events from now on to the active window in the desktop.

Implements DesktopInterface.

◆ textEventsEnabled()

bool DesktopSDL2::textEventsEnabled ( void ) const

inlinevirtual

Enable K_TEXT events from now on to the active window in the desktop.

Implements DesktopInterface.

Definition at line 174 of file DesktopSDL2.h.

◆ copyFromClipboard()

std::string DesktopSDL2::copyFromClipboard ( void ) const

virtual

Return a copy of the text existing in the clipboard, if any.

Throw if no clipboard or any error.

Implements DesktopInterface.

◆ copyToClipboard()

void DesktopSDL2::copyToClipboard ( const std::string & txt ) const

virtual

Copy TXT, if not empty, to the clipboard.

Throw if no clipboard or any error.

Implements DesktopInterface.

◆ PalWinSDL2

class PalWinSDL2

A palettized window managed by SDL2.

Definition at line 221 of file DesktopSDL2.h.

Inheritance diagram for PalWinSDL2:

[legend]

Collaboration diagram for PalWinSDL2:

[legend]

Public Member Functions
virtual	~PalWinSDL2 (void)
	Destructor: close the window.

	PalWinSDL2 (const PalWinSDL2 &)=delete
	Copies forbidden.

PalWinSDL2 &	operator= (const PalWinSDL2 &)=delete
	Assignments forb.

	PalWinSDL2 (PalWinSDL2 &&)=delete
	Moves forbidden.

PalWinSDL2 &	operator= (PalWinSDL2 &&)=delete
	Assignment-moves forb.

Cursor	getCursor (unsigned x=0, unsigned y=0) noexcept
	Get a non-checking cursor that points to that pixel. More...

CursorCheck	getCursorCheck (unsigned x=0, unsigned y=0)
	Get a checking cursor that points to that pixel. More...

PaletteIndex	getPixel (const Cursor &cursor)
	Return the value of the pixel at CURSOR in the window, if all is valid. More...

void	setPixel (const Cursor &cursor, PaletteIndex b)
	Set pixel at CURSOR to B, if all is valid. More...

void	fillRect (const Rectangle &r, PaletteIndex c)
	Fill a rectangle in the window with the given color, efficiently. More...

void	refresh (const Rectangle &rect=Rectangle{})
	Render the internal displayable data onto the desktop window. More...

void	serveEvents (const PalettizedWindow::Event::IDSet &whichevents={true}, ListOfEvents *evs=nullptr)
	Serve pending events. More...

void	setPaletteColors (const PaletteLevel *colors, PaletteIndex first, PaletteIndex count)
	Change color(s) in the palette of the window. More...

bool	getPointingInWindow (unsigned &x, unsigned &y, bool &leftbutton, bool &rightbutton)
	Get the status of the mouse within the entire window. More...

bool	keyPressed (DesktopInterface::KeyID k)
	Check whether the key K is pressed now when the focus is on the window. More...

void	updateKeypressMap (DesktopInterface::KeypressMap &map)
	Update MAP with key press information when the focus is on the window. More...

Public Member Functions inherited from PalettizedWindow
virtual	~PalettizedWindow (void)
	Destructor (derived classes must close the window).

	PalettizedWindow (const PalettizedWindow &)=delete
	Copies forbidden.

PalettizedWindow &	operator= (const PalettizedWindow &)=delete
	forb.

	PalettizedWindow (PalettizedWindow &&)=delete
	Moves forbidden.

PalettizedWindow &	operator= (PalettizedWindow &&)=delete
	forbidden.

unsigned	width (void) const noexcept
	Return the width in (non-scaled) pixels of the window. More...

unsigned	height (void) const noexcept
	Return the height in (non-scaled) pixels of the window. More...

Friends
class	DesktopSDL2
	For the desktop interface to create windows. More...

Additional Inherited Members
Public Types inherited from PalettizedWindow
typedef uint8_t	PaletteLevel
	Intensity of a color component (r, g, b). More...

typedef uint8_t	PaletteIndex
	Index of a color in the palette. More...

Static Public Attributes inherited from PalettizedWindow
static constexpr unsigned	NUMCOLSPAL = 256
	No. of colors in palette. More...

Protected Member Functions inherited from PalettizedWindow
	PalettizedWindow (const std::string &tit, unsigned dimw, unsigned dimh, unsigned scalex, unsigned scaley)
	Constructor. More...

Protected Attributes inherited from PalettizedWindow
const std::string	title_
	Title of the window. More...

const size_t	size_
	Size in pixels of the window. More...

const unsigned	width_
	Unscaled dims of the bitmap drawable. More...

const unsigned	height_
	Unscaled dims of the bitmap drawable. More...

const unsigned	scx_
	Scale of the bitmap when rendered. More...

const unsigned	scy_
	Scale of the bitmap when rendered. More...

const unsigned	swidth_
	Scaled dim of bitmap (dim of window). More...

const unsigned	sheight_
	Scaled dim of bitmap (dim of window). More...

Member Function Documentation

◆ getCursor()

Cursor PalWinSDL2::getCursor	(	unsigned	x = `0`,
		unsigned	y = `0`
	)

virtualnoexcept

Get a non-checking cursor that points to that pixel.

Implements PalettizedWindow.

◆ getCursorCheck()

CursorCheck PalWinSDL2::getCursorCheck	(	unsigned	x = `0`,
		unsigned	y = `0`
	)

virtual

Get a checking cursor that points to that pixel.

Implements PalettizedWindow.

◆ getPixel()

PaletteIndex PalWinSDL2::getPixel ( const Cursor & cursor )

virtual

Return the value of the pixel at CURSOR in the window, if all is valid.

Otherwise, exception is raised.

Implements PalettizedWindow.

◆ setPixel()

void PalWinSDL2::setPixel	(	const Cursor &	cursor,
		PaletteIndex	b
	)

virtual

Set pixel at CURSOR to B, if all is valid.

Otherwise, exception is raised.

Implements PalettizedWindow.

◆ fillRect()

void PalWinSDL2::fillRect	(	const Rectangle &	r,
		PaletteIndex	c
	)

virtual

Fill a rectangle in the window with the given color, efficiently.

Exception if some part of the rectangle falls outside the window.

Implements PalettizedWindow.

◆ refresh()

void PalWinSDL2::refresh ( const Rectangle & rect = Rectangle{} )

virtual

Render the internal displayable data onto the desktop window.

This method must be called from the main thread. It is performed through SDL blitting, which is slower than accessing directly the pixels in the framebuffer and refreshing them, but still gets important savings when rendering less than the entire window. RECT is the area condireded to be changed since the last refresh; this method uses it to do less data processing during the rendering, but the entire window is actually rendered. If RECT is empty, the entire displayable data is considered to be changed since the last call to the method.

Implements PalettizedWindow.

◆ serveEvents()

void PalWinSDL2::serveEvents	(	const PalettizedWindow::Event::IDSet &	whichevents = `{true}`,
		ListOfEvents *	evs = `nullptr`
	)

virtual

Serve pending events.

Fill EVS with those indicated in WHICHEVENTS that have occurred. if EVS != nullptr. EVS is not cleared first. This method must be called from the main thread.

Implements PalettizedWindow.

◆ setPaletteColors()

void PalWinSDL2::setPaletteColors	(	const PaletteLevel *	colors,
		PaletteIndex	first,
		PaletteIndex	count
	)

virtual

Change color(s) in the palette of the window.

Change colors from the color number FIRST to the number FIRST+COUNT-1 in the palette, to the content of COLORS. This can be done outside the main thread of the program.

Implements PalettizedWindow.

◆ getPointingInWindow()

bool PalWinSDL2::getPointingInWindow	(	unsigned &	x,
		unsigned &	y,
		bool &	leftbutton,
		bool &	rightbutton
	)

virtual

Get the status of the mouse within the entire window.

Return the (unscaled) position of the user pointing device and two main buttons (TRUE-> pressed). This method may be called from a thread different from the main one. This method returns FALSE if the pointer is outside the drawable area of the window.

NOTE:

-See the notes in DesktopInterface.

Implements PalettizedWindow.

◆ keyPressed()

bool PalWinSDL2::keyPressed ( DesktopInterface::KeyID k )

virtual

Check whether the key K is pressed now when the focus is on the window.

NOTE:

-See the notes in DesktopInterface.

Implements PalettizedWindow.

◆ updateKeypressMap()

void PalWinSDL2::updateKeypressMap ( DesktopInterface::KeypressMap & map )

virtual

Update MAP with key press information when the focus is on the window.

NOTE:

-See the notes in DesktopInterface.

Implements PalettizedWindow.

Friends And Related Function Documentation

◆ DesktopSDL2

friend class DesktopSDL2

friend

For the desktop interface to create windows.

Definition at line 223 of file DesktopSDL2.h.

Macro Definition Documentation

◆ SDL_MAIN_HANDLED

#define SDL_MAIN_HANDLED

#include <DesktopSDL2.h>

Definition at line 37 of file DesktopSDL2.h.

Description

Classes

Class Documentation

◆ DesktopSDL2

Static Public Member Functions

Public Member Functions

Additional Inherited Members

Member Function Documentation

◆ theDesktop()

◆ readPNGImageFile()

◆ writePNGImageFile()

◆ createWindow()

◆ getDesktopResolution()

◆ playSound()

◆ pausePlaying()

◆ resumePlaying()

◆ playingPaused()

◆ soundPlaying()

◆ nextSoundPlayingTime()

◆ lastSoundProducer()

◆ lastSoundDuration()

◆ enableTextEvents()

◆ disableTextEvents()

◆ textEventsEnabled()

◆ copyFromClipboard()

◆ copyToClipboard()

◆ PalWinSDL2

Public Member Functions

Friends

Additional Inherited Members

Member Function Documentation

◆ getCursor()

◆ getCursorCheck()

◆ getPixel()

◆ setPixel()

◆ fillRect()

◆ refresh()

◆ serveEvents()

◆ setPaletteColors()

◆ getPointingInWindow()

◆ keyPressed()

◆ updateKeypressMap()

Friends And Related Function Documentation

◆ DesktopSDL2

Macro Definition Documentation

◆ SDL_MAIN_HANDLED