Manages all the rendering at the level of the observer's surroundings. More...

#include <LandscapeMgr.hpp>

Public Slots
float	getLuminance () const
	Return the global landscape luminance [0..1], for being used e.g for setting eye adaptation. More...

float	getAtmosphereAverageLuminance () const
	return average luminance [cd/m^2] of atmosphere. Expect 10 at sunset, 6400 in daylight, >0 in dark night.

void	setAtmosphereAverageLuminance (const float overrideLuminance)
	Override autocomputed value and set average luminance [cd/m^2] of atmosphere. More...

static QMap< QString, QString >	getNameToDirMap ()
	Return a map of landscape names to landscape IDs (directory names).

QStringList	getAllLandscapeNames () const
	Retrieve a list of the names of all the available landscapes in the file search path sub-directories of the landscape area. More...

QStringList	getAllLandscapeIDs () const
	Retrieve a list of the identifiers of all the available landscapes in the file search path sub-directories of the landscape area. More...

QStringList	getUserLandscapeIDs () const
	Retrieve a list of the identifiers of all user-installed landscapes. More...

const QString	getCurrentLandscapeID () const
	Get the current landscape ID.

bool	setCurrentLandscapeID (const QString &id, const double changeLocationDuration=1.0)
	Change the current landscape to the landscape with the ID specified. More...

QString	getCurrentLandscapeName () const
	Get the current landscape name.

bool	setCurrentLandscapeName (const QString &name, const double changeLocationDuration=1.0)
	Change the current landscape to the landscape with the name specified. More...

float	getCurrentLandscapeBrightness (const bool light=false) const
	Get the current landscape or lightscape brightness (0..1) More...

bool	precacheLandscape (const QString &id, const bool replace=true)
	Preload a landscape into cache. More...

bool	removeCachedLandscape (const QString &id)
	Remove a landscape from the cache of landscapes. More...

void	setCacheSize (int mb)
	Set size of the landscape cache, in MB. More...

int	getCacheSize () const
	Retrieve total size of cache (MB).

int	getCacheFilledSize () const
	Retrieve sum of currently used memory in cache (MB, approximate)

int	getCacheCount () const
	Return number of landscapes already in the cache.

Landscape *	getCurrentLandscape () const
	Get the current landscape object.

const QString	getDefaultLandscapeID () const
	Get the default landscape ID.

bool	setDefaultLandscapeID (const QString &id)
	Change the default landscape to the landscape with the ID specified. More...

QString	getCurrentLandscapeHtmlDescription () const
	Return a pseudo HTML formatted string with all informations on the current landscape.

QString	getDescription () const
	Return a pseudo HTML formatted string with information from description or ini file.

bool	getFlagLandscape () const
	Get flag for displaying Landscape.

void	setFlagLandscape (const bool displayed)
	Set flag for displaying Landscape.

bool	getIsLandscapeFullyVisible () const
	Get whether the landscape is currently visible. If true, objects below landscape's limiting altitude limit can be omitted.

double	getLandscapeSinMinAltitudeLimit () const
	Get the sine of current landscape's minimal altitude. Useful to construct bounding caps.

bool	getFlagFog () const
	Get flag for displaying Fog.

void	setFlagFog (const bool displayed)
	Set flag for displaying Fog.

bool	getFlagIllumination () const
	Get flag for displaying illumination layer.

void	setFlagIllumination (const bool on)
	Set flag for displaying illumination layer.

bool	getFlagLabels () const
	Get flag for displaying landscape labels.

void	setFlagLabels (const bool on)
	Set flag for displaying landscape labels.

bool	getFlagPolyLineDisplayed () const
	Retrieve flag for rendering polygonal line (if one is defined)

void	setFlagPolyLineDisplayed (bool b)
	Set flag for rendering polygonal line (if one is defined)

int	getPolyLineThickness () const
	Retrieve thickness for rendering polygonal line (if one is defined)

void	setPolyLineThickness (int thickness)
	Set thickness for rendering polygonal line (if one is defined)

bool	getFlagLandscapeSetsLocation () const
	Return the value of the flag determining if a change of landscape will update the observer location.

void	setFlagLandscapeSetsLocation (bool b)
	Set the value of the flag determining if a change of landscape will update the observer location.

bool	getFlagLandscapeUseMinimalBrightness () const
	Return the value of the flag determining if a minimal brightness should be used to keep landscape visible.

void	setFlagLandscapeUseMinimalBrightness (bool b)
	Set the value of the flag determining if a minimal brightness should be used to keep landscape visible.

bool	getFlagLandscapeSetsMinimalBrightness () const
	Return the value of the flag determining if the minimal brightness should be taken from landscape.ini.

void	setFlagLandscapeSetsMinimalBrightness (bool b)
	Sets the value of the flag determining if the minimal brightness should be taken from landscape.ini.

double	getDefaultMinimalBrightness () const
	Return the minimal brightness value of the landscape.

void	setDefaultMinimalBrightness (const double b)
	Set the minimal brightness value of the landscape.

void	setFlagUseLightPollutionFromDatabase (const bool usage)
	Sets the value of the flag usage light pollution (and bortle index) from locations database.

bool	getFlagUseLightPollutionFromDatabase () const
	Return the value of flag usage light pollution (and bortle index) from locations database.

bool	getFlagCardinalsPoints () const
	Get flag for displaying Cardinals Points.

void	setFlagCardinalsPoints (const bool displayed)
	Set flag for displaying Cardinals Points.

Vec3f	getColorCardinalPoints () const
	Get Cardinals Points color.

void	setColorCardinalPoints (const Vec3f &v)
	Set Cardinals Points color.

bool	getFlagAtmosphere () const
	Get flag for displaying Atmosphere.

void	setFlagAtmosphere (const bool displayed)
	Set flag for displaying Atmosphere.

float	getAtmosphereFadeIntensity () const
	Get current display intensity of atmosphere ([0..1], for smoother transitions)

float	getAtmosphereFadeDuration () const
	Get atmosphere fade duration in s.

void	setAtmosphereFadeDuration (const float f)
	Set atmosphere fade duration in s.

void	setZRotation (const float d)
	Set the rotation of the landscape about the z-axis. More...

QString	installLandscapeFromArchive (QString pathToSourceArchive, const bool display=false, const bool forAllUsers=false)
	Install a landscape from a ZIP archive. More...

bool	removeLandscape (const QString landscapeID)
	This function removes a landscape from the user data directory. More...

QString	loadLandscapeName (const QString landscapeID)
	This function reads a landscape's name from its configuration file. More...

quint64	loadLandscapeSize (const QString landscapeID) const
	This function calculates and returns a landscape's disc size in bytes. More...

bool	getFlagLandscapeAutoSelection () const
	Get flag for autoselect of landscapes for planets.

void	setFlagLandscapeAutoSelection (bool enableAutoSelect)
	Set flag for autoselect of landscapes for planets.

bool	getFlagEnvironmentAutoEnable () const
	Get flag for auto-enable of atmospheres and landscapes for planets.

void	setFlagEnvironmentAutoEnable (bool b)
	Set flag for auto-enable atmosphere and landscape for planets with atmospheres in location window.

float	getLandscapeOpacity (Vec3d azalt) const
	Forward opacity query to current landscape. More...

float	getLandscapeOpacity (Vec3f azalt) const

float	getLandscapeOpacity (float azimuth, float altitude) const
	Forward opacity query to current landscape. More...

Signals
void	atmosphereDisplayedChanged (const bool displayed)

void	cardinalsPointsDisplayedChanged (const bool displayed)

void	cardinalsPointsColorChanged (const Vec3f &newColor) const

void	fogDisplayedChanged (const bool displayed)

void	landscapeDisplayedChanged (const bool displayed)

void	illuminationDisplayedChanged (const bool displayed)

void	labelsDisplayedChanged (const bool displayed)

void	flagPolyLineDisplayedChanged (const bool enabled)

void	polyLineThicknessChanged (const int thickness)

void	flagUseLightPollutionFromDatabaseChanged (const bool usage)

void	flagLandscapeAutoSelectionChanged (const bool value)

void	flagLandscapeSetsLocationChanged (const bool value)

void	flagLandscapeUseMinimalBrightnessChanged (const bool value)

void	flagLandscapeSetsMinimalBrightnessChanged (const bool value)

void	defaultMinimalBrightnessChanged (const double value)

void	setFlagEnvironmentAutoEnableChanged (const bool enabled)

void	defaultLandscapeChanged (const QString &id)
	Emitted whenever the default landscape is changed. More...

void	landscapesChanged ()
	Emitted when a landscape has been installed or un-installed. More...

void	errorUnableToOpen (QString path)
	Emitted when installLandscapeFromArchive() can't read from, write to or create a file or a directory. More...

void	errorNotArchive ()
	Emitted when the file passed to installLandscapeFromArchive() is not a ZIP archive or does not contain a valid landscape. More...

void	errorNotUnique (QString nameOrID)
	Emitted when installLandscapeFromArchive() tries to install a landscape with the same name or identifier as an already installed one. More...

void	errorRemoveManually (QString path)
	Emitted when removeLandscape() is unable to remove all the files of a landscape. More...

void	currentLandscapeChanged (QString currentLandscapeID, QString currentLandscapeName)
	Emitted when the current landscape was changed. More...

Public Member Functions
virtual void	init ()
	Initialize the LandscapeManager class. More...

virtual void	draw (StelCore *core)
	Draw the atmosphere, landscape graphics, and cardinal points.

void	drawPolylineOnly (StelCore *core)
	Draw landscape graphics and cardinal points. More...

virtual void	update (double deltaTime)
	Update time-dependent state. More...

virtual double	getCallOrder (StelModuleActionName actionName) const
	Get the order in which this module will draw its objects relative to other modules.

Landscape *	createFromFile (const QString &landscapeFile, const QString &landscapeId)
	Create a new landscape from the files which describe it. More...

Public Member Functions inherited from StelModule
virtual void	deinit ()
	Called before the module will be delete, and before the openGL context is suppressed. More...

virtual QSettings *	getSettings ()
	Return module-specific settings. More...

virtual QString	getModuleVersion () const
	Get the version of the module, default is stellarium main version.

virtual QString	getAuthorName () const
	Get the name of the module author.

virtual QString	getAuthorEmail () const
	Get the email adress of the module author.

virtual void	handleMouseClicks (class QMouseEvent *)
	Handle mouse clicks. More...

virtual void	handleMouseWheel (class QWheelEvent *)
	Handle mouse wheel. More...

virtual bool	handleMouseMoves (int x, int y, Qt::MouseButtons b)
	Handle mouse moves. More...

virtual void	handleKeys (class QKeyEvent *e)
	Handle key events. More...

virtual bool	handlePinch (qreal scale, bool started)
	Handle pinch gesture events. More...

virtual bool	configureGui (bool show=true)
	Detect or show the configuration GUI elements for the module. More...

Properties
bool	atmosphereDisplayed

bool	cardinalsPointsDisplayed

Vec3f	cardinalsPointsColor

bool	fogDisplayed

bool	landscapeDisplayed

bool	illuminationDisplayed

bool	labelsDisplayed

bool	flagPolyLineDisplayedOnly
	control drawing of a Polygonal line, if one is defined.

int	polyLineThickness
	thickness of polygonal horizon line

bool	flagUseLightPollutionFromDatabase

bool	flagLandscapeAutoSelection

bool	flagLandscapeSetsLocation

bool	flagLandscapeUseMinimalBrightness
	Indicate use of the default minimal brightness value specified in config.ini.

bool	flagLandscapeSetsMinimalBrightness
	Indicate use of the minimal brightness value specified in the current landscape.ini, if present.

double	defaultMinimalBrightness
	A minimal brightness value to keep landscape visible.

bool	flagEnvironmentAutoEnabling
	Indicate auto-enable atmosphere and landscape for planets with atmospheres in location window.

QString	currentLandscapeID
	The ID of the currently loaded landscape.

QStringList	allLandscapeNames

QString	currentLandscapeName

QString	currentLandscapeHtmlDescription

QString	defaultLandscapeID
	The ID of the default landscape.

Additional Inherited Members
Public Types inherited from StelModule
enum	StelModuleSelectAction { AddToSelection, ReplaceSelection, RemoveFromSelection }
	Enum used when selecting objects to define whether to add to, replace, or remove from the existing selection list. More...

enum	StelModuleActionName { ActionDraw, ActionUpdate, ActionHandleMouseClicks, ActionHandleMouseMoves, ActionHandleKeys }
	Define the possible action for which an order is defined. More...

Protected Member Functions inherited from StelModule
class StelAction *	addAction (const QString &id, const QString &groupId, const QString &text, QObject target, const char slot, const QString &shortcut="", const QString &altShortcut="")
	convenience methods to add an action (call to slot) to the StelActionMgr object. More...

class StelAction *	addAction (const QString &id, const QString &groupId, const QString &text, const char *slot, const QString &shortcut="", const QString &altShortcut="")
	convenience methods to add an action (call to own slot) to the StelActionMgr object. More...

StelAction *	addAction (const QString &id, const QString &groupId, const QString &text, QObject *contextObject, std::function< void()> lambda, const QString &shortcut="", const QString &altShortcut="")
	convenience methods to add an action (call to Lambda functor) to the StelActionMgr object. More...

Detailed Description

This includes landscape textures, fog, atmosphere and cardinal points. I decided to put all these elements together in a single class because they are inherently linked, especially when we start moving the observer in altitude.

Note: The Bortle scale index setting was removed from this class, because it was duplicated from StelSkyDrawer, complicating code that changes it. It is now only in StelSkyDrawer and can be accessed with getBortleScaleIndex and setBortleScaleIndex . Slots setAtmosphereBortleLightPollution and getAtmosphereBortleLightPollution in this class have been removed/made private. If script access is desired, use StelMainScriptAPI::get /setBortleScaleIndex

Member Function Documentation

◆ createFromFile()

Landscape* LandscapeMgr::createFromFile	(	const QString &	landscapeFile,
		const QString &	landscapeId
	)

Reads a landscape.ini file which is passed as the first parameter, determines the landscape type, and creates a new object for the landscape of the proper type. The load member is then called, passing both parameters.

Parameters

landscapeFile	This is the path to a landscape.ini file.
landscapeId	This is the landscape ID, which is also the name of the directory in which the files (textures and so on) for the landscape reside.

Returns: A pointer to the newly created landscape object.

◆ currentLandscapeChanged

void LandscapeMgr::currentLandscapeChanged	(	QString	currentLandscapeID,
		QString	currentLandscapeName
	)

signal

Parameters

currentLandscapeID	the ID of the new landscape
currentLandscapeName	the name of the new landscape

◆ defaultLandscapeChanged

void LandscapeMgr::defaultLandscapeChanged ( const QString & id )

signal

Parameters

id	the landscape id of the new default landscape

◆ drawPolylineOnly()

void LandscapeMgr::drawPolylineOnly ( StelCore * core )

This only will redraw a polygonal line (if defined), the gazetteer and the Cardinal points. This can be called outside the usual call order, if any foreground has to be overdrawn, e.g. 3D sceneries.

◆ errorNotArchive

void LandscapeMgr::errorNotArchive ( )

signal

(A way of moving the need for translatable error messages to the GUI.)

◆ errorNotUnique

void LandscapeMgr::errorNotUnique ( QString nameOrID )

signal

(A way of moving the need for translatable error messages to the GUI.)

Parameters

nameOrID the name or the identifier of the landscape

◆ errorRemoveManually

void LandscapeMgr::errorRemoveManually ( QString path )

signal

(A way of moving the need for translatable error messages to the GUI.)

Parameters

path	the path to the landscape's directory

◆ errorUnableToOpen

void LandscapeMgr::errorUnableToOpen ( QString path )

signal

(A way of moving the need for translatable error messages to the GUI.)

Parameters

path	path to the file or directory

◆ getAllLandscapeIDs

QStringList LandscapeMgr::getAllLandscapeIDs ( ) const

slot

Returns: the identifiers of the landscapes, which are the names of the directories containing the landscapes' files

◆ getAllLandscapeNames

QStringList LandscapeMgr::getAllLandscapeNames ( ) const

slot

Returns: the names of the landscapes, which are the values of the name parameter in the landscape.ini files

◆ getCurrentLandscapeBrightness

float LandscapeMgr::getCurrentLandscapeBrightness ( const bool light = false ) const

inlineslot

Parameters

light true to retrieve the light layer brightness value.

◆ getLandscapeOpacity [1/2]

float LandscapeMgr::getLandscapeOpacity ( Vec3d azalt ) const

inlineslot

Parameters

azalt direction of view line to sample in azaltimuth coordinates.

◆ getLandscapeOpacity [2/2]

float LandscapeMgr::getLandscapeOpacity	(	float	azimuth,
		float	altitude
	)		const

inlineslot

Parameters

azimuth	in degrees
altitude	in degrees

◆ getLuminance

float LandscapeMgr::getLuminance ( ) const

slot

It returns 1 if atmosphere drawing is on and no eclipse underway, 0 if atmosphere is switched off. The actual brightness is of no concern here. You may use getAtmosphereAverageLuminance() for this.

◆ getUserLandscapeIDs

QStringList LandscapeMgr::getUserLandscapeIDs ( ) const

slot

Effectively, this returns the results of getAllLandscapeIDs() without the landscapes specified in the #packagedLandscapeIDs list.

◆ init()

virtual void LandscapeMgr::init ( )

virtual

Operations performed:

Load the default landscape as specified in the application configuration
Set up landscape-related display flags from ini parser object

Implements StelModule.

◆ installLandscapeFromArchive

QString LandscapeMgr::installLandscapeFromArchive	(	QString	pathToSourceArchive,
		const bool	display = `false`,
		const bool	forAllUsers = `false`
	)

slot

This function searches for a file named "landscape.ini" in the root directory of the archive. If it is not found there, the function searches inside the topmost sub-directories (if any), but no deeper. If a landscape configuration file is found:

if a "landscapes" directory does not exist in the user data directory, it is created;
inside it, a sub-directory is created with the landscape identifier for a name;
all files in the archive directory that contains the "landscape.ini" file are extracted to the new sub-directory of "landscapes";
all sub-directories of that archive directory will be skipped along with any other files or directories in the archive.

The landscape identifier is either:

the name of the folder in the archive that contains "landscape.ini",
or the first 65 (or less) characters of the archive name, if the "landscape.ini" file is in the nameless root directory of the archive.

The landscape identifier must be unique.

Parameters

pathToSourceArchive	path to the source archive file.
display	If true, the landscape will be set to be the current landscape after installation.
forAllUsers	If true, this function will try to install the landscape in a way that meakes it is available to all users of this computer. May require running Stellarium as an administrator (root) on some Windows or *nix systems. (NOT IMPLEMENTED!)

Returns: the installed landscape's identifier, or an empty string on failure.

◆ landscapesChanged

void LandscapeMgr::landscapesChanged ( )

signal

For example, it is used to update the list of landscapes in the Sky and viewing options window (the ViewDialog class)

◆ loadLandscapeName

QString LandscapeMgr::loadLandscapeName ( const QString landscapeID )

slot

Parameters

landscapeID an installed landscape's identifier (the folder name)

Returns: an empty string if there is no such landscape or some other error occurs

◆ loadLandscapeSize

quint64 LandscapeMgr::loadLandscapeSize ( const QString landscapeID ) const

slot

It adds up the sizes of all files in the landscape's folder. It assumes that there are no sub-directories. (There shouldn't be any anyway.)

Parameters

landscapeID an installed landscape's identifier (the folder name)

◆ precacheLandscape

bool LandscapeMgr::precacheLandscape	(	const QString &	id,
		const bool	replace = `true`
	)

slot

Parameters

id	the ID of a landscape
replace	true if existing landscape entry should be replaced (useful during development to reload after edit)

Returns: false if landscape could not be found, or if it already existed in cache and replace was false.

◆ removeCachedLandscape

bool LandscapeMgr::removeCachedLandscape ( const QString & id )

slot

Parameters

id	the ID of a landscape

Returns: false if landscape could not be found

◆ removeLandscape

bool LandscapeMgr::removeLandscape ( const QString landscapeID )

slot

It tries to recursively delete all files in the landscape directory and then remove it from the list of available landscapes. If the function encounters any file that can't be deleted it aborts the operation (previously deleted files are not restored). Landscapes that were packaged with Stellarium can't be removed, thanks to the #packagedLandscapeIDs list.

Parameters

landscapeID an installed landscape's identifier (the folder name)

◆ setAtmosphereAverageLuminance

void LandscapeMgr::setAtmosphereAverageLuminance ( const float overrideLuminance )

slot

This is around 10 at sunset, 6400 in daylight, >0 in dark night. Usually there is no need to call this, the luminance is properly computed. This is a function which can be useful in rare cases, e.g. in scripts when you want to create images of adjacent sky regions with the same brightness setting, or for creation of a virtual camera which can deliberately show over- or underexposure. For these cases, it is advisable to first center the brightest luminary (sun or moon), call getAtmosphereAverageLuminance() and then set this value explicitly to freeze it during image export. To unfreeze, call this again with any negative value.

◆ setCacheSize

void LandscapeMgr::setCacheSize ( int mb )

inlineslot

Default size is 100MB, or configured as [landscape/cache_size_mb] from config.ini. The landscape sizes returned in Landscape::getMemorySize() are only approximate, but include image and texture sizes. A big landscape may well take 150MB or more. On a 32bit system, keep this rather small. On 64bit with 16GB RAM and no other tasks, 4GB is no problem. Modern GPUs may have 4 or even 8GB of dedicated texture memory. Most of this may be filled with landscape textures. Example: a museum installation with 20 large (16384x2048) old_style landscapes can require up to 3.5GB. Allow 4GB cache, and the system will never have to load a landscape during the show when all have been preloaded.

◆ setCurrentLandscapeID

bool LandscapeMgr::setCurrentLandscapeID	(	const QString &	id,
		const double	changeLocationDuration = `1.0`
	)

slot

Emits currentLandscapeChanged() if the landscape changed (true returned)

Parameters

id	the ID of the new landscape
changeLocationDuration	the duration of the transition animation

Returns: false if the new landscape could not be set (e.g. no landscape of that ID was found).

◆ setCurrentLandscapeName

bool LandscapeMgr::setCurrentLandscapeName	(	const QString &	name,
		const double	changeLocationDuration = `1.0`
	)

slot

Emits currentLandscapeChanged() if the landscape changed (true returned)

Parameters

name	the name of the new landscape, as found in the landscape:name key of the landscape.ini file.
changeLocationDuration	the duration of the transition animation

◆ setDefaultLandscapeID

bool LandscapeMgr::setDefaultLandscapeID ( const QString & id )

slot

Parameters

id	the ID of the landscape to use by default

Returns: false if the new landscape could not be set (e.g. no landscape of that ID was found). True on success.

◆ setZRotation

void LandscapeMgr::setZRotation ( const float d )

slot

This is intended for special uses such as when the landscape consists of a vehicle which might change orientation over time (e.g. a ship).

Parameters

d	the rotation angle in degrees as an offset from the originally loaded value.

◆ update()

virtual void LandscapeMgr::update ( double deltaTime )

virtual

Includes:

Landscape, atmosphere and cardinal point on/off fading.
Atmophere colour calculation based on location, position of sun and moon.
updates adaptation luminescence based on visible bright objects.
Landscape and lightscape brightness computations based on sun position and whether atmosphere is on or off.

Implements StelModule.

Public Slots

Signals

Public Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ createFromFile()

◆ currentLandscapeChanged

◆ defaultLandscapeChanged

◆ drawPolylineOnly()

◆ errorNotArchive

◆ errorNotUnique

◆ errorRemoveManually

◆ errorUnableToOpen

◆ getAllLandscapeIDs

◆ getAllLandscapeNames

◆ getCurrentLandscapeBrightness

◆ getLandscapeOpacity [1/2]

◆ getLandscapeOpacity [2/2]

◆ getLuminance

◆ getUserLandscapeIDs

◆ init()

◆ installLandscapeFromArchive

◆ landscapesChanged

◆ loadLandscapeName

◆ loadLandscapeSize

◆ precacheLandscape

◆ removeCachedLandscape

◆ removeLandscape

◆ setAtmosphereAverageLuminance

◆ setCacheSize

◆ setCurrentLandscapeID

◆ setCurrentLandscapeName

◆ setDefaultLandscapeID

◆ setZRotation

◆ update()