#include <Surface.hpp>

Inheritance diagram for gamp::wt::Surface:

Collaboration diagram for gamp::wt::Surface:

Classes
struct	Private

Public Types
enum class	lock_status_t : uint16_t { unlocked , not_ready , locked_changed , locked_same }

Public Member Functions
	Surface (const Surface &)=delete

	Surface (Private, handle_t surface_handle, const Vec2i &surface_size, const Capabilities &requested)
	Private ctor for single Surface::create() method w/o public ctor.

virtual	~Surface () noexcept
	Releases this instance.

const Capabilities *	capabilities () const noexcept
	Returns the chosen (retrieved) capabilities of a realized surface.

bool	createContext (const gamp::render::RenderProfile &profile, const gamp::render::RenderContextFlags &contextFlags)

virtual void	dispose (const jau::fraction_timespec &) noexcept

virtual void	disposedNotify (const jau::fraction_timespec &) noexcept

constexpr bool	isBLOriented () const noexcept
	Returns `true` if this surface is rendered in OpenGL's coordinate system, origin at bottom left.

virtual bool	isValid () const noexcept

lock_status_t	lockSurface ()
	Lock the surface of this native window.

void	operator= (const Surface &)=delete

const gamp::render::RenderContext *	renderContext () const noexcept

gamp::render::RenderContext *	renderContext () noexcept

void	setRequestedCapabilities (CapabilitiesPtr &&req) noexcept
	Sets the requested capabilities for a surface to be realized.

bool	setSwapInterval (int v) noexcept
	Returns true if swap interval could be set with the native toolkit post createContext().

const SurfaceSRef	shared ()

constexpr handle_t	surfaceHandle () const noexcept
	Returns the handle to the surface for this NativeSurface.

constexpr const Vec2i &	surfaceSize () const noexcept
	Returns the surface size of the client area excluding insets (window decorations) in pixel units.

virtual bool	surfaceSwap () noexcept
	Provide a mechanism to utilize custom (pre-) swap surface code.

constexpr int	swapInterval () const noexcept
	Returns desired or determined swap interval.

std::string	toString () const noexcept

void	unlockSurface ()
	Unlock the surface of this native window.

Static Public Member Functions
static SurfaceSRef	create (handle_t surface_handle, const Vec2i &surface_size, const Capabilities &requested)

static gamp::render::RenderContextPtr	createContext (const wt::SurfaceSRef &surface, const gamp::render::RenderProfile &profile, const gamp::render::RenderContextFlags &contextFlags, gamp::render::RenderContext *shareWith) noexcept

static constexpr bool	is_locked (const lock_status_t ls) noexcept

Static Public Attributes
static constexpr const jau::fraction_i64	TIMEOUT = 5_s

Protected Member Functions
virtual lock_status_t	nativeSurfaceLock () noexcept

virtual void	nativeSurfaceUnlock () noexcept

void	setSurfaceSize (const Vec2i &sz) noexcept

template<typename ChildT>
std::shared_ptr< ChildT >	shared_from_base ()

Static Protected Member Functions
static void	setCaps (handle_t surface_handle, const Capabilities &requested) noexcept

Detailed Description

Definition at line 38 of file Surface.hpp.

Member Enumeration Documentation

◆ lock_status_t

enum class gamp::wt::Surface::lock_status_t : uint16_t

strong

Enumerator
unlocked
not_ready
locked_changed
locked_same

Definition at line 42 of file Surface.hpp.

Constructor & Destructor Documentation

◆ Surface() [1/2]

gamp::wt::Surface::Surface	(	Private	,
		handle_t	surface_handle,
		const Vec2i &	surface_size,
		const Capabilities &	requested )

inline

Private ctor for single Surface::create() method w/o public ctor.

Definition at line 81 of file Surface.hpp.

Here is the caller graph for this function:

◆ Surface() [2/2]

gamp::wt::Surface::Surface ( const Surface & )

delete

◆ ~Surface()

virtual gamp::wt::Surface::~Surface ( )

inlinevirtualnoexcept

Releases this instance.

Definition at line 94 of file Surface.hpp.

Member Function Documentation

◆ is_locked()

static constexpr bool gamp::wt::Surface::is_locked ( const lock_status_t ls )

inlinestaticconstexprnoexcept

Definition at line 46 of file Surface.hpp.

Here is the caller graph for this function:

◆ setCaps()

void Surface::setCaps	(	handle_t	surface_handle,
		const Capabilities &	requested )

staticprotectednoexcept

Definition at line 95 of file gamp_sdl2_gl.cpp.

Here is the caller graph for this function:

◆ shared_from_base()

template<typename ChildT>

std::shared_ptr< ChildT > gamp::wt::Surface::shared_from_base ( )

inlineprotected

Definition at line 70 of file Surface.hpp.

Here is the caller graph for this function:

◆ setSurfaceSize()

void gamp::wt::Surface::setSurfaceSize ( const Vec2i & sz )

inlineprotectednoexcept

Definition at line 74 of file Surface.hpp.

◆ nativeSurfaceLock()

virtual lock_status_t gamp::wt::Surface::nativeSurfaceLock ( )

inlineprotectedvirtualnoexcept

Definition at line 76 of file Surface.hpp.

Here is the caller graph for this function:

◆ nativeSurfaceUnlock()

virtual void gamp::wt::Surface::nativeSurfaceUnlock ( )

inlineprotectedvirtualnoexcept

Definition at line 77 of file Surface.hpp.

◆ create()

static SurfaceSRef gamp::wt::Surface::create	(	handle_t	surface_handle,
		const Vec2i &	surface_size,
		const Capabilities &	requested )

inlinestatic

Definition at line 84 of file Surface.hpp.

◆ operator=()

void gamp::wt::Surface::operator= ( const Surface & )

delete

◆ disposedNotify()

virtual void gamp::wt::Surface::disposedNotify ( const jau::fraction_timespec & )

inlinevirtualnoexcept

Reimplemented in gamp::wt::Window.

Definition at line 100 of file Surface.hpp.

Here is the caller graph for this function:

◆ dispose()

virtual void gamp::wt::Surface::dispose ( const jau::fraction_timespec & )

inlinevirtualnoexcept

Reimplemented in gamp::wt::Window.

Definition at line 104 of file Surface.hpp.

Here is the caller graph for this function:

◆ shared()

const SurfaceSRef gamp::wt::Surface::shared ( )

inline

Definition at line 115 of file Surface.hpp.

Here is the caller graph for this function:

◆ createContext() [1/2]

bool gamp::wt::Surface::createContext	(	const gamp::render::RenderProfile &	profile,
		const gamp::render::RenderContextFlags &	contextFlags )

inline

Definition at line 117 of file Surface.hpp.

Here is the caller graph for this function:

◆ createContext() [2/2]

gamp::render::RenderContextPtr Surface::createContext	(	const wt::SurfaceSRef &	surface,
		const gamp::render::RenderProfile &	profile,
		const gamp::render::RenderContextFlags &	contextFlags,
		gamp::render::RenderContext *	shareWith )

staticnoexcept

Definition at line 125 of file gamp_sdl2_gl.cpp.

◆ renderContext() [1/2]

const gamp::render::RenderContext * gamp::wt::Surface::renderContext ( ) const

inlinenoexcept

Definition at line 131 of file Surface.hpp.

Here is the caller graph for this function:

◆ renderContext() [2/2]

gamp::render::RenderContext * gamp::wt::Surface::renderContext ( )

inlinenoexcept

Definition at line 134 of file Surface.hpp.

◆ capabilities()

const Capabilities * gamp::wt::Surface::capabilities ( ) const

inlinenoexcept

Returns the chosen (retrieved) capabilities of a realized surface.

Definition at line 139 of file Surface.hpp.

◆ setRequestedCapabilities()

void gamp::wt::Surface::setRequestedCapabilities ( CapabilitiesPtr && req )

inlinenoexcept

Sets the requested capabilities for a surface to be realized.

Definition at line 142 of file Surface.hpp.

◆ swapInterval()

int gamp::wt::Surface::swapInterval ( ) const

inlineconstexprnoexcept

Returns desired or determined swap interval.

Defaults to -1, i.e. adaptive swap interval.

Use setSwapInterval() to set the swap interval.

[1..n] denotes the swap interval
0 indicates no swap interval, e.g. by failed setSwapInterval()
-1 indicates adaptive swap interval

Definition at line 153 of file Surface.hpp.

◆ setSwapInterval()

bool gamp::wt::Surface::setSwapInterval ( int v )

inlinenoexcept

Returns true if swap interval could be set with the native toolkit post createContext().

See swapInterval().

Definition at line 156 of file Surface.hpp.

◆ isBLOriented()

bool gamp::wt::Surface::isBLOriented ( ) const

inlineconstexprnoexcept

Returns true if this surface is rendered in OpenGL's coordinate system, origin at bottom left.

Otherwise returns false, i.e. origin at top left.

Default impl. is true, i.e. OpenGL bottom-left coordinate system.

Currently only MS-Windows bitmap offscreen drawable uses a non OpenGL orientation and hence returns false.
This removes the need of a vertical flip when used in AWT or Windows applications.

Definition at line 174 of file Surface.hpp.

Here is the caller graph for this function:

◆ surfaceSize()

const Vec2i & gamp::wt::Surface::surfaceSize ( ) const

inlineconstexprnoexcept

Returns the surface size of the client area excluding insets (window decorations) in pixel units.

Definition at line 177 of file Surface.hpp.

Here is the caller graph for this function:

◆ surfaceHandle()

handle_t gamp::wt::Surface::surfaceHandle ( ) const

inlineconstexprnoexcept

Returns the handle to the surface for this NativeSurface.

The surface handle should be set/update by lockSurface(), where unlockSurface() is not allowed to modify it. After unlockSurface() it is no more guaranteed that the surface handle is still valid.

The surface handle shall reflect the platform one for all drawable surface operations, e.g. opengl, swap-buffer.

On X11 this returns an entity of type Window, since there is no differentiation of surface and window there.
On Microsoft Windows this returns an entity of type HDC.

Definition at line 194 of file Surface.hpp.

Here is the caller graph for this function:

◆ isValid()

virtual bool gamp::wt::Surface::isValid ( ) const

inlinevirtualnoexcept

Reimplemented in gamp::wt::Window.

Definition at line 196 of file Surface.hpp.

◆ surfaceSwap()

virtual bool gamp::wt::Surface::surfaceSwap ( )

inlinevirtualnoexcept

Provide a mechanism to utilize custom (pre-) swap surface code.

This method is called before the render toolkit (e.g. JOGL) swaps the buffer/surface if double buffering is enabled.

The implementation may itself apply the swapping, in which case true shall be returned.

Returns: true if this method completed swapping the surface, otherwise false, in which case eg the GLDrawable implementation has to swap the code.

Reimplemented in gamp::wt::Window.

Definition at line 210 of file Surface.hpp.

◆ lockSurface()

lock_status_t gamp::wt::Surface::lockSurface ( )

inline

Lock the surface of this native window.

The surface handle shall be valid after a successfull call, i.e. return a value other than lock_status_t::unlocked and lock_status_t::not_ready.

The caller may need to take care of the result lock_status_t::locked_changed, where the surface handle is valid but has changed.

This call is blocking until the surface has been locked or a timeout is reached. The latter will throw a runtime exception.

This call allows recursion from the same thread.

The implementation may want to aquire the application level com.jogamp.common.util.locks.RecursiveLock first before proceeding with a native surface lock.

The implementation shall also invoke AbstractGraphicsDevice#lock() for the initial lock (recursive count zero).

Returns: Surface::lock_status_t

Exceptions

RuntimeException	after timeout when waiting for the surface lock
NativeWindowException	if native locking failed, maybe platform related

Definition at line 238 of file Surface.hpp.

◆ unlockSurface()

void gamp::wt::Surface::unlockSurface ( )

inline

Unlock the surface of this native window.

Shall not modify the surface handle, see lockSurface().

The implementation shall also invoke GraphicsDevice::unlock() for the final unlock (recursive count zero).

The implementation shall be fail safe, i.e. tolerant in case the native resources are already released / unlocked. In this case the implementation shall simply ignore the call.

See also: lockSurface()

Definition at line 266 of file Surface.hpp.

◆ toString()

std::string gamp::wt::Surface::toString ( ) const

inlinenoexcept

Definition at line 274 of file Surface.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ TIMEOUT

const jau::fraction_i64 gamp::wt::Surface::TIMEOUT = 5_s

staticconstexpr

Definition at line 40 of file Surface.hpp.

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

include/gamp/wt/Surface.hpp
src/gamp_sdl2_gl.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ lock_status_t

Constructor & Destructor Documentation

◆ Surface() [1/2]

◆ Surface() [2/2]

◆ ~Surface()

Member Function Documentation

◆ is_locked()

◆ setCaps()

◆ shared_from_base()

◆ setSurfaceSize()

◆ nativeSurfaceLock()

◆ nativeSurfaceUnlock()

◆ create()

◆ operator=()

◆ disposedNotify()

◆ dispose()

◆ shared()

◆ createContext() [1/2]

◆ createContext() [2/2]

◆ renderContext() [1/2]

◆ renderContext() [2/2]

◆ capabilities()

◆ setRequestedCapabilities()

◆ swapInterval()

◆ setSwapInterval()

◆ isBLOriented()

◆ surfaceSize()

◆ surfaceHandle()

◆ isValid()

◆ surfaceSwap()

◆ lockSurface()

◆ unlockSurface()

◆ toString()

Member Data Documentation

◆ TIMEOUT