The Engine class is the central part of SGCT and handles most of the callbacks, rendering, network handling, input devices, etc. More...

#include <sgct/engine.h>

Classes
struct	Statistics
	Structure with all statistics gathered about different frametimes. More...
struct	Settings
struct	Callbacks
	This struct holds all of the callback functions that can be used by the client library to be called during the different times of the frame. More...

Public Types
using	DrawFunction = void (*)(const RenderData&)

Public Member Functions
void	terminate ()
	Signals to SGCT that the application should be terminated at the end of the next frame.
void	exec ()
	This function starts the SGCT render loop in which the rendering, synchronization, event handling, and everything else happens.
const Statistics &	statistics () const
	Returns the Engine::Statistics object that contains all collected information about the frametimes, drawtimes, and other frame-based statistics.
float	nearClipPlane () const
	Returns the distance to the near clipping plane in meters.
float	farClipPlane () const
	Returns the distance to the far clipping plane in meters.
void	setNearAndFarClippingPlanes (float nearClippingPlane, float farClippingPlane)
	Set the near and far clipping planes.
void	updateFrustums () const
	This functions updates the frustum of all viewports.
const Window *	focusedWindow () const
	Return the Window that currently has the focus.
void	setStatsGraphVisibility (bool value)
	Determines whether the graph displaying the rendering stats is being displayed or not.
float	statsGraphScale () const
	Returns the current scaling value used to render the statistics graphs if they are enabled.
void	setStatsGraphScale (float scale)
	Sets the new scaling value for the statistics graph rendering.
vec2	statsGraphOffset () const
	Returns the current offset value used to render the statistics graphics away from the center of the screen if they are enabled.
void	setStatsGraphOffset (vec2 offset)
	Sets the new offet value for the statistics graph rendering.
void	takeScreenshot (std::vector< int > windowIds=std::vector< int >())
	Takes an RGBA screenshot and saves it as a PNG file.
void	resetScreenshotNumber ()
	Resets the screenshot number to 0.
void	setScreenshotNumber (unsigned int number)
	Sets the number that the next screenshot will recieve with the next call of takeScreenshot.
unsigned int	screenShotNumber () const
	Returns the number the next screenshot will receive upon the next call of takeScreenshot.
Engine::DrawFunction	drawFunction () const
	This function returns the draw function to be used in internal classes that need to repeatedly call this.
Engine::DrawFunction	draw2DFunction () const
const Node &	thisNode () const
	Returns a reference to the node that represents this computer.
const std::vector< std::unique_ptr< Window > > &	windows () const
	Returns a list of all windows for the current node.
bool	isMaster () const
	Returns if this Node is the master in a clustered environment.
unsigned int	currentFrameNumber () const
	Returns the number of the current frame.
void	setCapturePath (std::filesystem::path path)
	Set capture/screenshot path used by SGCT.
void	setCaptureFromBackBuffer (bool state)
	Set if capture should capture warped from backbuffer instead of texture.
StatisticsRenderer *	statisticsRenderer ()
const Settings &	settings () const

Static Public Member Functions
static Engine &	instance ()
	Returns the global Engine object that is created through the Engine::create function.
static void	create (config::Cluster cluster, Callbacks callbacks, const Configuration &arg)
	Creates the singleton Engine that is accessible through the Engine::instance function.
static void	destroy ()
	Destroys the singleton Engine instance that was created by Engine::create and that is accessible through the Engine::instance function.
static User &	defaultUser ()
	Returns a pointer to the default user, i.e.

Detailed Description

The Engine class is the central part of SGCT and handles most of the callbacks, rendering, network handling, input devices, etc.

Member Typedef Documentation

◆ DrawFunction

using sgct::Engine::DrawFunction = void (*)(const RenderData&)

Member Function Documentation

◆ create()

void sgct::Engine::create	(	config::Cluster	cluster,
		Callbacks	callbacks,
		const Configuration &	arg )

static

Creates the singleton Engine that is accessible through the Engine::instance function.

This function can only be called while no Engine instance exists, which means that either it has to be the first call to this function or the destroy function was called in between.

Parameters

cluster	The configuration object for the config::Cluster that contains the information about how many nodes should exist, how many windows each node should contain and all other potential objects. The result of this is, in general, loaded from a configuration file
callbacks	The list of callbacks that should be registered and called during the frame and their correct times. All callbacks are optional
arg	The parameters that were set by the user from the commandline that can override some of the behavior from the configuration

◆ currentFrameNumber()

unsigned int sgct::Engine::currentFrameNumber ( ) const

Returns the number of the current frame.

The frame number is a monotonically increasing number that will never be repeated.

Returns: The current framenumber

◆ defaultUser()

User & sgct::Engine::defaultUser ( )

static

Returns a pointer to the default user, i.e.

the observer position.

Returns: A pointer to the default user

◆ destroy()

void sgct::Engine::destroy ( )

static

Destroys the singleton Engine instance that was created by Engine::create and that is accessible through the Engine::instance function.

If this function is called without a valid singleton existing, it is a no-op.

◆ draw2DFunction()

Engine::DrawFunction sgct::Engine::draw2DFunction ( ) const

◆ drawFunction()

Engine::DrawFunction sgct::Engine::drawFunction ( ) const

This function returns the draw function to be used in internal classes that need to repeatedly call this.

In general, there is no need for external applications to store the draw function, but they are free to do so.

Returns: The currently bound draw function

◆ exec()

void sgct::Engine::exec ( )

This function starts the SGCT render loop in which the rendering, synchronization, event handling, and everything else happens.

Control will only return from this function after the program is terminated for any reason or if a non-recoverable error has occurred.

◆ farClipPlane()

float sgct::Engine::farClipPlane ( ) const

Returns the distance to the far clipping plane in meters.

Returns: The distance to the far clipping plane in meters

◆ focusedWindow()

const Window * sgct::Engine::focusedWindow ( ) const

Return the Window that currently has the focus.

If no SGCT window has focus, a nullptr is returned.

Returns: The focus window or nullptr if no such window exists

◆ instance()

Engine & sgct::Engine::instance ( )

static

Returns the global Engine object that is created through the Engine::create function.

This function must only be called after the Engine::create function has been called successfully.

Returns: The global Engine object responsible for this application

Exceptions

std::logic_error This error is thrown if this function is called before the Engine::create function is called or after the Engine::destroy function was called

◆ isMaster()

bool sgct::Engine::isMaster ( ) const

Returns if this Node is the master in a clustered environment.

This function will also return true if the Node is not part of a clustered environment.

Returns: true if this Node is the master in a clustered environment or not part of a cluster; false otherwise

◆ nearClipPlane()

float sgct::Engine::nearClipPlane ( ) const

Returns the distance to the near clipping plane in meters.

Returns: The distance to the near clipping plane in meters

◆ resetScreenshotNumber()

void sgct::Engine::resetScreenshotNumber ( )

Resets the screenshot number to 0.

◆ screenShotNumber()

unsigned int sgct::Engine::screenShotNumber ( ) const

Returns the number the next screenshot will receive upon the next call of takeScreenshot.

This counter can be reset through setScreenshotNumber.

Returns: The number the next screenshot will receive

◆ setCaptureFromBackBuffer()

void sgct::Engine::setCaptureFromBackBuffer ( bool state )

Set if capture should capture warped from backbuffer instead of texture.

Backbuffer data includes masks and warping.

◆ setCapturePath()

void sgct::Engine::setCapturePath ( std::filesystem::path path )

Set capture/screenshot path used by SGCT.

Parameters

path	The path including filename without suffix

◆ setNearAndFarClippingPlanes()

void sgct::Engine::setNearAndFarClippingPlanes	(	float	nearClippingPlane,
		float	farClippingPlane )

Set the near and far clipping planes.

This operation recalculates all frustums for all viewports.

Parameters

nearClippingPlane	The near clipping plane in meters
farClippingPlane	The far clipping plane in meters

◆ setScreenshotNumber()

void sgct::Engine::setScreenshotNumber ( unsigned int number )

Sets the number that the next screenshot will recieve with the next call of takeScreenshot.

Parameters

number The next screenshot number

◆ setStatsGraphOffset()

void sgct::Engine::setStatsGraphOffset ( vec2 offset )

Sets the new offet value for the statistics graph rendering.

This value determines the placement of the center of the graphs on the screen and is usually in the range of [0,1]. If the statistics graph is currently not showing, calling this function will not have any effects.

Parameters

offset The new offset value for the statistics graph rendering

◆ setStatsGraphScale()

void sgct::Engine::setStatsGraphScale ( float scale )

Sets the new scaling value for the statistics graph rendering.

This value must be in the range [0,1]. If the statistics graph is currently not showing, calling this function will not have any effects.

Parameters

scale The new scaling value for the statistics graph rendering

◆ setStatsGraphVisibility()

void sgct::Engine::setStatsGraphVisibility ( bool value )

Determines whether the graph displaying the rendering stats is being displayed or not.

Parameters

value The new desired state as to whether the statistics are being shown

◆ settings()

const Settings & sgct::Engine::settings ( ) const

◆ statistics()

const Statistics & sgct::Engine::statistics ( ) const

Returns the Engine::Statistics object that contains all collected information about the frametimes, drawtimes, and other frame-based statistics.

The reference returned by this function is valid until the Engine::destroy function is called.

Returns: The Statistics object containing all of the statistics information

◆ statisticsRenderer()

StatisticsRenderer * sgct::Engine::statisticsRenderer ( )

◆ statsGraphOffset()

vec2 sgct::Engine::statsGraphOffset ( ) const

Returns the current offset value used to render the statistics graphics away from the center of the screen if they are enabled.

If the statistics graphs are currently not shown, an error value of {-1, -1} is returned instead.

Returns: The current offset value for the statistics graph

◆ statsGraphScale()

float sgct::Engine::statsGraphScale ( ) const

Returns the current scaling value used to render the statistics graphs if they are enabled.

If the statistics graphs are currently not shown, an error value of -1 is returned instead.

Returns: The current scaling value for the statistics graph

◆ takeScreenshot()

void sgct::Engine::takeScreenshot ( std::vector< int > windowIds = std::vector< int >() )

Takes an RGBA screenshot and saves it as a PNG file.

If stereo rendering is enabled then two screenshots will be saved per frame, one for each eye. The filename for each image is the window title with an incremental counter appended to it. Each successive call of this function will increment the counter. If it is desired to reset the counter, see setScreenshotNumber.

To record frames for a movie simply call this function every frame you wish to record. The write to disk is multi-threaded.

Parameters

windowIds If the vector is empty, screenshots of all windows will be taken, otherwise only the Window ids that appear in the vector will be used for screenshots and Window ids that do not appear in the list are ignored

◆ terminate()

void sgct::Engine::terminate ( )

Signals to SGCT that the application should be terminated at the end of the next frame.

◆ thisNode()

const Node & sgct::Engine::thisNode ( ) const

Returns a reference to the node that represents this computer.

Returns: A reference to this node

◆ updateFrustums()

void sgct::Engine::updateFrustums ( ) const

This functions updates the frustum of all viewports.

If a viewport is tracked, this is done on the fly.

◆ windows()

const std::vector< std::unique_ptr< Window > > & sgct::Engine::windows ( ) const

Returns a list of all windows for the current node.

This vector might be empty, and is valid for the lifetime of the program until the Engine::destroy function is called.

Returns: A list of all windows for the current node

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

sgct/engine.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ DrawFunction

Member Function Documentation

◆ create()

◆ currentFrameNumber()

◆ defaultUser()

◆ destroy()

◆ draw2DFunction()

◆ drawFunction()

◆ exec()

◆ farClipPlane()

◆ focusedWindow()

◆ instance()

◆ isMaster()

◆ nearClipPlane()

◆ resetScreenshotNumber()

◆ screenShotNumber()

◆ setCaptureFromBackBuffer()

◆ setCapturePath()

◆ setNearAndFarClippingPlanes()

◆ setScreenshotNumber()

◆ setStatsGraphOffset()

◆ setStatsGraphScale()

◆ setStatsGraphVisibility()

◆ settings()

◆ statistics()

◆ statisticsRenderer()

◆ statsGraphOffset()

◆ statsGraphScale()

◆ takeScreenshot()

◆ terminate()

◆ thisNode()

◆ updateFrustums()

◆ windows()