The default window backend, on SDL3. More...

#include <gui_core/windows/sdl/gui_window_backend_sdl.h>

Inheritance diagram for tachyon::SDLWindowBackend:

Public Types
using	Options = SDLWindowBackendOptions
	See SDLWindowBackendOptions.

Public Member Functions
	SDLWindowBackend (const Options &options={})
	Starts SDL video if needed; failing that, logs an error and the backend makes no windows.
	~SDLWindowBackend () override
void	SetGraphicsContext (GraphicsContext *graphicsContext) override
	Windows are created for graphicsContext->GetAPI(); for a VulkanGraphicsContext this also installs its SDL surface factory.
OSWindowHandle	CreateWindow (std::string_view title, int2 size, tachyon::WindowFlags windowFlags, OSWindowHandle parentOSHandle) override
	Creates a window whose client area is size pixels, placed by the OS.
OSWindowHandle	CreateWindow (std::string_view title, IntRect rect, tachyon::WindowFlags windowFlags, OSWindowHandle parentOSHandle) override
	Creates a window whose client area is rect (screen pixels); otherwise as the size overload.
void	AttachInputHandlerToWindow (OSWindowHandle window, IPlatformInputHandler *inputHandler) override
	Where the window's input goes (see IPlatformInputHandler); not owned, nullptr for none.
void	AttachContextToWindow (OSWindowHandle window, IWindowContext *context) override
	Stores the window's context (not owned), for GetWindowContext, for the ID passed with the window's input, and for PollEvents' cleanup.
bool	DestroyWindow (OSWindowHandle) override
	Queues the window for destruction: the next PollEvents passes its context to cleanup, then destroys it.
void	DetachWindowContext (OSWindowHandle) override
	Clears the context pointer stored in the OS window, so PollEvents' cleanup callback gets nullptr instead of double-freeing a context the caller destroys.
bool	IsWindow (OSWindowHandle) override
	True while the handle is a live window of this backend; false once it was destroyed (by code or the user) and for nullptr.
IWindowContext *	GetWindowContext (OSWindowHandle) override
	The context attached with AttachContextToWindow, or nullptr.
void	BringToFront (OSWindowHandle) override
	Raises the window above the others and asks the OS for the input focus.
OSWindowHandle	GetWindowUnderMouse () override
	The backend's window under the mouse, or nullptr.
OSWindowHandle	GetActiveWindow () override
	The window with the keyboard focus, or nullptr when none of the backend's windows has it.
uint32_t	GetFocusChangeCount () const override
	Goes up whenever keyboard focus moves between windows, or to or from another application; open popups are checked against it.
void	PollEvents (std::function< void(OSWindowHandle, IWindowContext *)> cleanup) override
	Handles the OS's pending events, delivering input to the attached handlers.
int2	GetScreenMousePos () override
	The mouse position in screen pixels (SDL: as of the last PollEvents).
std::optional< color4b >	ReadScreenPixel (int2 screenPos) override
	The color of a screen pixel, anywhere on the desktop (an eyedropper); nothing where the platform can't read the screen.
bool	TakeCloseRequest (OSWindowHandle window) override
	Whether the OS asked to close a WindowFlags::ConfirmClose window since last asked.
MouseButtons	GetMouseButtons () override
	The mouse buttons held down, wherever the mouse is (SDL: as of the last PollEvents).
float	GetDoubleClickMilliseconds () override
	The OS's double-click time in milliseconds, or 0 where the platform has none.
uint32_t	ShowFade (OSWindowHandle window, IWindowContext *context, IntRect screenRect, float opacity) override
	A layered stand-in for window showing what context drew last, at screenRect (screen pixels) and opacity (0 to 1), so the window itself can be hidden or cloaked while it fades in or out.
void	MoveFade (uint32_t fade, IntRect screenRect, float opacity) override
	Moves a stand-in and sets its opacity.
void	EndFade (uint32_t fade) override
	Removes a stand-in.
bool	PrefersReducedMotion () override
	Whether the OS asks for less motion (animations turned off); false where the platform has no such setting.
void	SetCursor (MouseCursor cursor) override
	Shows the system cursor for that shape; MouseCursor::None hides the cursor.
void	SetTextInputArea (OSWindowHandle window, IntRect rect) override
	Where text is being typed in the window (window coordinates), so the IME places its candidate list next to it.
float	GetWindowDisplayScale (OSWindowHandle window) override
	The UI scale the OS asks for in this window: pixel density times the monitor's content scale (1.5 on a 150% display).
IntRect	GetWindowPixelRect (OSWindowHandle window) override
	The window's render target: OS position (for OS compositing) and size in physical pixels.
void	SwapBuffers (OSWindowHandle) override
	Presents for a graphics API that swaps through the window (OpenGL).
IntRect	GetWindowRect (OSWindowHandle) override
	Client area in pixels; {0,0,0,0} while minimized.
int2	GetWindowPos (OSWindowHandle) override
	The client area's top-left in screen pixels.
int2	GetWindowSize (OSWindowHandle) override
	The client area's size in pixels; {0,0} while minimized.
bool	SetWindowRect (OSWindowHandle, const IntRect &clientRect) override
	Moves and resizes the window so its client area is clientRect (screen pixels); the backend accounts for the frame.
void	SetWindowVisible (OSWindowHandle, bool visible) override
	Shows or hides the window; hiding doesn't destroy it.
bool	SetWindowCloaked (OSWindowHandle, bool cloaked) override
	Cloaks a shown window: it takes frames but stays invisible, so it can be drawn before it appears.
void	SetWindowMode (OSWindowHandle, WindowMode) override
	Sets the window's state: minimized, maximized, restored or fullscreen.
WindowMode	GetWindowMode (OSWindowHandle) const override
	The window's state as the OS has it now; WindowMode::Normal by default.
std::vector< MonitorInfo >	GetMonitors () const override
	Every monitor, the primary first.
int	GetMonitorAt (int2 pos) const override
	Index into GetMonitors of the monitor holding the screen point pos; 0 (the primary) when no monitor holds it, -1 without monitors.
int	GetMonitorFromWindow (OSWindowHandle handle) const override
	Index into GetMonitors of the window's monitor; -1 for an unknown window.
uint32_t	GetTicks () const override
	A millisecond clock (SDL: since SDL started).
std::string	GetPreferredLanguage () const override
	The user's preferred language as a BCP 47 tag ("ja", "en-US"), or empty when the platform doesn't say.
int32_t	GetCursorSize () const override
	The OS mouse cursor's size in pixels (its accessibility size at the display's scale), or 0 when the platform doesn't say.
void *	GetNativeHandle (OSWindowHandle) override
	The OS's own window handle, passed to GraphicsContext::CreateWindowContext (HWND on Windows, NSWindow on macOS, an X11 window or Wayland surface on Linux); nullptr without one.
int2	WindowPointToPixels (SDL_Window *window, float x, float y) const
	A position inside window (OS window coordinates) in screen pixels.
SDL_Window *	ModalBlockerFor (const SDL_Event *event) const
	The modal window that blocks the event's window (one of ours), or null.
Public Member Functions inherited from tachyon::IWindowBackend
	IWindowBackend ()
virtual	~IWindowBackend ()
void	SetWindowMovedCallback (std::function< void()> cb)
	Sets cb, called as soon as any window moves or resizes, even inside the OS modal move / resize loop (before the next frame), so it must be safe outside the frame.
void	SetHitTestCallback (std::function< WindowHitArea(OSWindowHandle, int2 screenPos)> cb)
	Classifies points (screen pixels) of CustomTitleBar windows for the OS.
WindowHitArea	HitTestWindow (OSWindowHandle window, int2 screenPos) const
	What a point (screen pixels) of the window is, from the hit-test callback; WindowHitArea::Client without one.
static SDL_Window *	ToSDL (OSWindowHandle h)
	Converts between handles and SDL windows: a handle is the SDL_Window pointer.
static OSWindowHandle	FromSDL (SDL_Window *w)
	Converts between handles and SDL windows: a handle is the SDL_Window pointer.

Additional Inherited Members
Protected Attributes inherited from tachyon::IWindowBackend
std::function< void()>	m_onWindowMoved
	Set by SetWindowMovedCallback; a backend calls it when a window moves or resizes.
std::function< WindowHitArea(OSWindowHandle, int2)>	m_hitTest
	Set by SetHitTestCallback; a backend asks it through HitTestWindow.
GraphicsContext *	m_graphicsContext = nullptr
	Set by SetGraphicsContext; not owned.

Detailed Description

The default window backend, on SDL3.

Starts SDL's video subsystem unless it already runs, and then quits SDL again when destroyed.

Member Typedef Documentation

◆ Options

using tachyon::SDLWindowBackend::Options = SDLWindowBackendOptions

See SDLWindowBackendOptions.

Constructor & Destructor Documentation

◆ SDLWindowBackend()

tachyon::SDLWindowBackend::SDLWindowBackend ( const Options & options = {} )

explicit

Starts SDL video if needed; failing that, logs an error and the backend makes no windows.

◆ ~SDLWindowBackend()

tachyon::SDLWindowBackend::~SDLWindowBackend ( )

override

Member Function Documentation

◆ SetGraphicsContext()

void tachyon::SDLWindowBackend::SetGraphicsContext ( GraphicsContext * graphicsContext )

overridevirtual

Windows are created for graphicsContext->GetAPI(); for a VulkanGraphicsContext this also installs its SDL surface factory.

Reimplemented from tachyon::IWindowBackend.

◆ CreateWindow() [1/2]

OSWindowHandle tachyon::SDLWindowBackend::CreateWindow	(	std::string_view	title,
		int2	size,
		tachyon::WindowFlags	windowFlags,
		OSWindowHandle	parentOSHandle )

overridevirtual

Creates a window whose client area is size pixels, placed by the OS.

parentOSHandle is the owner window, or nullptr for a top-level one. Returns nullptr on failure.

Implements tachyon::IWindowBackend.

◆ CreateWindow() [2/2]

OSWindowHandle tachyon::SDLWindowBackend::CreateWindow	(	std::string_view	title,
		IntRect	rect,
		tachyon::WindowFlags	windowFlags,
		OSWindowHandle	parentOSHandle )

overridevirtual

Creates a window whose client area is rect (screen pixels); otherwise as the size overload.

Implements tachyon::IWindowBackend.

◆ AttachInputHandlerToWindow()

void tachyon::SDLWindowBackend::AttachInputHandlerToWindow	(	OSWindowHandle	window,
		IPlatformInputHandler *	inputHandler )

overridevirtual

Where the window's input goes (see IPlatformInputHandler); not owned, nullptr for none.

Implements tachyon::IWindowBackend.

◆ AttachContextToWindow()

void tachyon::SDLWindowBackend::AttachContextToWindow	(	OSWindowHandle	window,
		IWindowContext *	context )

overridevirtual

Stores the window's context (not owned), for GetWindowContext, for the ID passed with the window's input, and for PollEvents' cleanup.

nullptr clears it.

Implements tachyon::IWindowBackend.

◆ DestroyWindow()

bool tachyon::SDLWindowBackend::DestroyWindow ( OSWindowHandle )

overridevirtual

Queues the window for destruction: the next PollEvents passes its context to cleanup, then destroys it.

False for a handle that isn't one of the backend's windows.

Implements tachyon::IWindowBackend.

◆ DetachWindowContext()

void tachyon::SDLWindowBackend::DetachWindowContext ( OSWindowHandle )

overridevirtual

Clears the context pointer stored in the OS window, so PollEvents' cleanup callback gets nullptr instead of double-freeing a context the caller destroys.

Implements tachyon::IWindowBackend.

◆ IsWindow()

bool tachyon::SDLWindowBackend::IsWindow ( OSWindowHandle )

overridevirtual

True while the handle is a live window of this backend; false once it was destroyed (by code or the user) and for nullptr.

Implements tachyon::IWindowBackend.

◆ GetWindowContext()

IWindowContext * tachyon::SDLWindowBackend::GetWindowContext ( OSWindowHandle )

overridevirtual

The context attached with AttachContextToWindow, or nullptr.

Implements tachyon::IWindowBackend.

◆ BringToFront()

void tachyon::SDLWindowBackend::BringToFront ( OSWindowHandle )

overridevirtual

Raises the window above the others and asks the OS for the input focus.

Implements tachyon::IWindowBackend.

◆ GetWindowUnderMouse()

OSWindowHandle tachyon::SDLWindowBackend::GetWindowUnderMouse ( )

overridevirtual

The backend's window under the mouse, or nullptr.

Implements tachyon::IWindowBackend.

◆ GetActiveWindow()

OSWindowHandle tachyon::SDLWindowBackend::GetActiveWindow ( )

overridevirtual

The window with the keyboard focus, or nullptr when none of the backend's windows has it.

Implements tachyon::IWindowBackend.

◆ GetFocusChangeCount()

uint32_t tachyon::SDLWindowBackend::GetFocusChangeCount ( ) const

inlineoverridevirtual

Goes up whenever keyboard focus moves between windows, or to or from another application; open popups are checked against it.

Implements tachyon::IWindowBackend.

◆ PollEvents()

void tachyon::SDLWindowBackend::PollEvents ( std::function< void(OSWindowHandle, IWindowContext *)> cleanup )

overridevirtual

Handles the OS's pending events, delivering input to the attached handlers.

Then the windows destroyed since the last call (DestroyWindow, or closed by the OS) go: cleanup gets each handle and its context while the window still exists. Runs in UpdateFrame, and again in RecordFrame.

Implements tachyon::IWindowBackend.

◆ GetScreenMousePos()

int2 tachyon::SDLWindowBackend::GetScreenMousePos ( )

overridevirtual

The mouse position in screen pixels (SDL: as of the last PollEvents).

Implements tachyon::IWindowBackend.

◆ ReadScreenPixel()

std::optional< color4b > tachyon::SDLWindowBackend::ReadScreenPixel ( int2 screenPos )

overridevirtual

The color of a screen pixel, anywhere on the desktop (an eyedropper); nothing where the platform can't read the screen.

Reimplemented from tachyon::IWindowBackend.

◆ TakeCloseRequest()

bool tachyon::SDLWindowBackend::TakeCloseRequest ( OSWindowHandle window )

overridevirtual

Whether the OS asked to close a WindowFlags::ConfirmClose window since last asked.

Reimplemented from tachyon::IWindowBackend.

◆ GetMouseButtons()

MouseButtons tachyon::SDLWindowBackend::GetMouseButtons ( )

overridevirtual

The mouse buttons held down, wherever the mouse is (SDL: as of the last PollEvents).

Implements tachyon::IWindowBackend.

◆ GetDoubleClickMilliseconds()

float tachyon::SDLWindowBackend::GetDoubleClickMilliseconds ( )

overridevirtual

The OS's double-click time in milliseconds, or 0 where the platform has none.

Reimplemented from tachyon::IWindowBackend.

◆ ShowFade()

uint32_t tachyon::SDLWindowBackend::ShowFade	(	OSWindowHandle	window,
		IWindowContext *	context,
		IntRect	screenRect,
		float	opacity )

overridevirtual

A layered stand-in for window showing what context drew last, at screenRect (screen pixels) and opacity (0 to 1), so the window itself can be hidden or cloaked while it fades in or out.

Returns the stand-in, or 0 where there are none: then the window shows and hides at once.

Reimplemented from tachyon::IWindowBackend.

◆ MoveFade()

void tachyon::SDLWindowBackend::MoveFade	(	uint32_t	fade,
		IntRect	screenRect,
		float	opacity )

overridevirtual

Moves a stand-in and sets its opacity.

Reimplemented from tachyon::IWindowBackend.

◆ EndFade()

void tachyon::SDLWindowBackend::EndFade ( uint32_t fade )

overridevirtual

Removes a stand-in.

Reimplemented from tachyon::IWindowBackend.

◆ PrefersReducedMotion()

bool tachyon::SDLWindowBackend::PrefersReducedMotion ( )

overridevirtual

Whether the OS asks for less motion (animations turned off); false where the platform has no such setting.

Reimplemented from tachyon::IWindowBackend.

◆ SetCursor()

void tachyon::SDLWindowBackend::SetCursor ( MouseCursor cursor )

overridevirtual

Shows the system cursor for that shape; MouseCursor::None hides the cursor.

The library sets it once per frame.

Implements tachyon::IWindowBackend.

◆ SetTextInputArea()

void tachyon::SDLWindowBackend::SetTextInputArea	(	OSWindowHandle	window,
		IntRect	rect )

overridevirtual

Where text is being typed in the window (window coordinates), so the IME places its candidate list next to it.

Implements tachyon::IWindowBackend.

◆ GetWindowDisplayScale()

float tachyon::SDLWindowBackend::GetWindowDisplayScale ( OSWindowHandle window )

overridevirtual

The UI scale the OS asks for in this window: pixel density times the monitor's content scale (1.5 on a 150% display).

0 when unknown.

Implements tachyon::IWindowBackend.

◆ GetWindowPixelRect()

IntRect tachyon::SDLWindowBackend::GetWindowPixelRect ( OSWindowHandle window )

overridevirtual

The window's render target: OS position (for OS compositing) and size in physical pixels.

Implements tachyon::IWindowBackend.

◆ SwapBuffers()

void tachyon::SDLWindowBackend::SwapBuffers ( OSWindowHandle )

overridevirtual

Presents for a graphics API that swaps through the window (OpenGL).

The library doesn't call it: a Vulkan window context presents itself.

Implements tachyon::IWindowBackend.

◆ GetWindowRect()

IntRect tachyon::SDLWindowBackend::GetWindowRect ( OSWindowHandle )

overridevirtual

Client area in pixels; {0,0,0,0} while minimized.

Implements tachyon::IWindowBackend.

◆ GetWindowPos()

int2 tachyon::SDLWindowBackend::GetWindowPos ( OSWindowHandle )

overridevirtual

The client area's top-left in screen pixels.

Implements tachyon::IWindowBackend.

◆ GetWindowSize()

int2 tachyon::SDLWindowBackend::GetWindowSize ( OSWindowHandle )

overridevirtual

The client area's size in pixels; {0,0} while minimized.

Implements tachyon::IWindowBackend.

◆ SetWindowRect()

bool tachyon::SDLWindowBackend::SetWindowRect	(	OSWindowHandle	,
		const IntRect &	clientRect )

overridevirtual

Moves and resizes the window so its client area is clientRect (screen pixels); the backend accounts for the frame.

True on success.

Implements tachyon::IWindowBackend.

◆ SetWindowVisible()

void tachyon::SDLWindowBackend::SetWindowVisible	(	OSWindowHandle	,
		bool	visible )

overridevirtual

Shows or hides the window; hiding doesn't destroy it.

Implements tachyon::IWindowBackend.

◆ SetWindowCloaked()

bool tachyon::SDLWindowBackend::SetWindowCloaked	(	OSWindowHandle	,
		bool	cloaked )

overridevirtual

Cloaks a shown window: it takes frames but stays invisible, so it can be drawn before it appears.

False when the backend can't (then the window is hidden until drawn instead).

Reimplemented from tachyon::IWindowBackend.

◆ SetWindowMode()

void tachyon::SDLWindowBackend::SetWindowMode	(	OSWindowHandle	,
		WindowMode	)

overridevirtual

Sets the window's state: minimized, maximized, restored or fullscreen.

The default does nothing.

Reimplemented from tachyon::IWindowBackend.

◆ GetWindowMode()

WindowMode tachyon::SDLWindowBackend::GetWindowMode ( OSWindowHandle ) const

overridevirtual

The window's state as the OS has it now; WindowMode::Normal by default.

Reimplemented from tachyon::IWindowBackend.

◆ GetMonitors()

std::vector< MonitorInfo > tachyon::SDLWindowBackend::GetMonitors ( ) const

overridevirtual

Every monitor, the primary first.

Implements tachyon::IWindowBackend.

◆ GetMonitorAt()

int tachyon::SDLWindowBackend::GetMonitorAt ( int2 pos ) const

overridevirtual

Index into GetMonitors of the monitor holding the screen point pos; 0 (the primary) when no monitor holds it, -1 without monitors.

Implements tachyon::IWindowBackend.

◆ GetMonitorFromWindow()

int tachyon::SDLWindowBackend::GetMonitorFromWindow ( OSWindowHandle handle ) const

overridevirtual

Index into GetMonitors of the window's monitor; -1 for an unknown window.

Implements tachyon::IWindowBackend.

◆ GetTicks()

uint32_t tachyon::SDLWindowBackend::GetTicks ( ) const

overridevirtual

A millisecond clock (SDL: since SDL started).

Implements tachyon::IWindowBackend.

◆ GetPreferredLanguage()

std::string tachyon::SDLWindowBackend::GetPreferredLanguage ( ) const

overridevirtual

The user's preferred language as a BCP 47 tag ("ja", "en-US"), or empty when the platform doesn't say.

Reimplemented from tachyon::IWindowBackend.

◆ GetCursorSize()

int32_t tachyon::SDLWindowBackend::GetCursorSize ( ) const

overridevirtual

The OS mouse cursor's size in pixels (its accessibility size at the display's scale), or 0 when the platform doesn't say.

Reimplemented from tachyon::IWindowBackend.

◆ GetNativeHandle()

void * tachyon::SDLWindowBackend::GetNativeHandle ( OSWindowHandle )

overridevirtual

The OS's own window handle, passed to GraphicsContext::CreateWindowContext (HWND on Windows, NSWindow on macOS, an X11 window or Wayland surface on Linux); nullptr without one.

Implements tachyon::IWindowBackend.

◆ ToSDL()

SDL_Window * tachyon::SDLWindowBackend::ToSDL ( OSWindowHandle h )

inlinestatic

Converts between handles and SDL windows: a handle is the SDL_Window pointer.

◆ FromSDL()

OSWindowHandle tachyon::SDLWindowBackend::FromSDL ( SDL_Window * w )

inlinestatic

Converts between handles and SDL windows: a handle is the SDL_Window pointer.

◆ WindowPointToPixels()

int2 tachyon::SDLWindowBackend::WindowPointToPixels	(	SDL_Window *	window,
		float	x,
		float	y ) const

A position inside window (OS window coordinates) in screen pixels.

◆ ModalBlockerFor()

SDL_Window * tachyon::SDLWindowBackend::ModalBlockerFor ( const SDL_Event * event ) const

The modal window that blocks the event's window (one of ours), or null.

The documentation for this class was generated from the following file:

gui_core/windows/sdl/gui_window_backend_sdl.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Options

Constructor & Destructor Documentation

◆ SDLWindowBackend()

◆ ~SDLWindowBackend()

Member Function Documentation

◆ SetGraphicsContext()

◆ CreateWindow() [1/2]

◆ CreateWindow() [2/2]

◆ AttachInputHandlerToWindow()

◆ AttachContextToWindow()

◆ DestroyWindow()

◆ DetachWindowContext()

◆ IsWindow()

◆ GetWindowContext()

◆ BringToFront()

◆ GetWindowUnderMouse()

◆ GetActiveWindow()

◆ GetFocusChangeCount()

◆ PollEvents()

◆ GetScreenMousePos()

◆ ReadScreenPixel()

◆ TakeCloseRequest()

◆ GetMouseButtons()

◆ GetDoubleClickMilliseconds()

◆ ShowFade()

◆ MoveFade()

◆ EndFade()

◆ PrefersReducedMotion()

◆ SetCursor()

◆ SetTextInputArea()

◆ GetWindowDisplayScale()

◆ GetWindowPixelRect()

◆ SwapBuffers()

◆ GetWindowRect()

◆ GetWindowPos()

◆ GetWindowSize()

◆ SetWindowRect()

◆ SetWindowVisible()

◆ SetWindowCloaked()

◆ SetWindowMode()

◆ GetWindowMode()

◆ GetMonitors()

◆ GetMonitorAt()

◆ GetMonitorFromWindow()

◆ GetTicks()

◆ GetPreferredLanguage()

◆ GetCursorSize()

◆ GetNativeHandle()

◆ ToSDL()

◆ FromSDL()

◆ WindowPointToPixels()

◆ ModalBlockerFor()