Gamp v0.0.7-36-g24b1eb6
Gamp: Graphics, Audio, Multimedia and Processing
Loading...
Searching...
No Matches
gamp::wt::Surface Class Reference

#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)
 Private ctor for single Surface::create() method w/o public ctor.
 
virtual ~Surface () noexcept
 Releases this instance.
 
const Capabilitiescapabilities () const noexcept
 
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::RenderContextrenderContext () const noexcept
 
gamp::render::RenderContextrenderContext () noexcept
 
bool setSwapInterval (int v) noexcept
 Returns true if swap interval could be set with the native toolkit post createContext().
 
const SurfaceRef shared ()
 
constexpr handle_t surfaceHandle () const noexcept
 Returns the handle to the surface for this NativeSurface.
 
constexpr const Vec2isurfaceSize () 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 SurfaceRef create (handle_t surface_handle, const Vec2i &surface_size)
 
static gamp::render::RenderContextPtr createContext (const wt::SurfaceRef &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 ()
 

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

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

Definition at line 79 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 92 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:

◆ shared_from_base()

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

Definition at line 68 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 72 of file Surface.hpp.

◆ nativeSurfaceLock()

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

Definition at line 74 of file Surface.hpp.

Here is the caller graph for this function:

◆ nativeSurfaceUnlock()

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

Definition at line 75 of file Surface.hpp.

◆ create()

static SurfaceRef gamp::wt::Surface::create ( handle_t surface_handle,
const Vec2i & surface_size )
inlinestatic

Definition at line 82 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 98 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 102 of file Surface.hpp.

Here is the caller graph for this function:

◆ shared()

const SurfaceRef gamp::wt::Surface::shared ( )
inline

Definition at line 113 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 115 of file Surface.hpp.

Here is the caller graph for this function:

◆ createContext() [2/2]

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

Definition at line 83 of file gamp_sdl2_gl.cpp.

◆ renderContext() [1/2]

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

Definition at line 129 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 132 of file Surface.hpp.

◆ capabilities()

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

Definition at line 136 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 147 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 150 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 168 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 171 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 188 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 190 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 204 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
RuntimeExceptionafter timeout when waiting for the surface lock
NativeWindowExceptionif native locking failed, maybe platform related

Definition at line 232 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 260 of file Surface.hpp.

◆ toString()

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

Definition at line 268 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: