The Database class is a special type that is never intended to be instantiated. More...

#include <hps.h>

Static Public Member Functions
static void	Execute (bool in_once=true)
	This function will pump the stand-alone window event system once by default. More...

static Time	GetTime ()
	Queries the number of milliseconds that have elapsed since Visualize started. More...

static void	Sleep (Time milliseconds)
	Sleep for the number of milliseconds requested. More...

static void	RelinquishMemory ()
	Relinquish any internally cached memory to the system. More...

static void	ShowMemoryUsage (size_t &out_allocated, size_t &out_used)
	Returns information about system memory usage. More...

static void	Reset ()
	Performs a complete reset of the Visualize database. More...

static void	Synchronize ()
	Synchronizes the database, guaranteeing that all queued actions and updates have been performed. More...

static WindowKeyArray	GetWindowKeys ()
	Get a list of all windows (application, stand-alone, and offscreen) which are active (have been created but not deleted). More...

static SegmentKeyArray	GetRootSegments ()
	Get a list of all root segments which are active (have been created but not deleted). More...

static PortfolioKeyArray	GetPortfolios ()
	Get a list of all portfolios which are active (have been created but not deleted). More...

static PortfolioKey const	GetMaterialLibraryPortfolio ()
	Get the material library portfolio. More...

static ApplicationWindowKey	CreateApplicationWindow (WindowHandle in_window_handle, Window::Driver in_driver=Window::Driver::Default3D)
	Create an application window for the given window handle that Visualize can draw into with the specified driver. More...

static ApplicationWindowKey	CreateApplicationWindow (WindowHandle in_window_handle, ApplicationWindowOptionsKit const &in_options)
	Create an application window for the given window handle that Visualize can draw into with the specified options. More...

static StandAloneWindowKey	CreateStandAloneWindow (Window::Driver in_driver=Window::Driver::Default3D)
	Create a stand-alone window with the specified driver. More...

static StandAloneWindowKey	CreateStandAloneWindow (StandAloneWindowOptionsKit const &in_options)
	Create a stand-alone window with the specified options. More...

static OffScreenWindowKey	CreateOffScreenWindow (unsigned int in_width, unsigned int in_height, Window::Driver in_driver=Window::Driver::Default3D)
	Create an offscreen window of the given height and width with the specified driver. More...

static OffScreenWindowKey	CreateOffScreenWindow (unsigned int in_width, unsigned int in_height, OffScreenWindowOptionsKit const &in_options)
	Create an offscreen window of the given height and width with the specified options. More...

static OffScreenWindowKey	CreateOffScreenWindow (ImageDefinition const &in_destination_image, Window::Driver in_driver=Window::Driver::Default3D)
	Create an offscreen window with the specified driver. More...

static OffScreenWindowKey	CreateOffScreenWindow (ImageDefinition const &in_destination_image, OffScreenWindowOptionsKit const &in_options)
	Create an offscreen window of the given height and width with the specified options. More...

static SegmentKey	CreateRootSegment ()
	Create a new root segment, i.e., a segment without an owner. More...

static PortfolioKey	CreatePortfolio ()
	Create a new portfolio. More...

static EventDispatcher	CreateEventDispatcher ()
	Create a new EventDispatcher with a dedicated thread ready to dispatch events to handlers. More...

static EventDispatcher	CreateEventDispatcher (char const *in_name)
	Create a new EventDispatcher with a dedicated thread ready to dispatch events to handlers. More...

static size_t	SelectByShell (ShellKit const &in_shell, SelectionOptionsKit const &in_options, SelectionResults &out_results)
	Performs an object space selection by shell starting at the specified segment using the specified selection options. More...

static size_t	SelectByShell (ShellKey const &in_shell, SelectionOptionsKit const &in_options, SelectionResults &out_results)
	Performs an object space selection by shell starting at the specified segment using the specified selection options. More...

static size_t	SelectByVolume (SimpleCuboid const &in_volume, SelectionOptionsKit const &in_options, SelectionResults &out_results)
	Performs an object space selection by volume starting at the specified segment using the specified selection options. More...

static size_t	SelectByRay (Point const &in_start_point, Vector const &in_direction, SelectionOptionsKit const &in_options, SelectionResults &out_results)
	Performs an object space selection by ray starting at the specified segment using the specified selection options. More...

static EventDispatcher const &	GetEventDispatcher ()
	Get the event dispatcher associated with the database. More...

static bool	GetInformationEventFilter (HPS::Info::Code in_code)
	Provides the filter state of an InformationEvent. More...

static bool	GetWarningEventFilter (HPS::Info::Code in_code)
	Provides the filter state of a WarningEvents. More...

static bool	GetErrorEventFilter (HPS::Info::Code in_code)
	Provides the filter state of an ErrorEvent. More...

static bool	SetInformationEventFilter (HPS::Info::Code in_code, bool in_filtered)
	Sets if a specific code for InformationEvent should be filtered. More...

static bool	SetWarningEventFilter (HPS::Info::Code in_code, bool in_filtered)
	Sets if a specific code for WarningEvent should be filtered. More...

static bool	SetErrorEventFilter (HPS::Info::Code in_code, bool in_filtered)
	Sets if a specific code for ErrorEvent should be filtered. More...

static void	SetEmergencyHandler (HPS::EmergencyHandler const &in_emergency_handler)
	Sets a custom EmergencyHandler. More...

static void	UnsetEmergencyHandler ()
	Sets the default EmergencyHandler. More...

static size_t	GetSoftMemoryLimit ()
	Gets the value at which the EmergencyHandler will be activated for SoftMemoryLimit. More...

static size_t	SetSoftMemoryLimit (size_t in_limit_bytes)
	Sets the value at which the EmergencyHandler will be activated for SoftMemoryLimit. More...

static size_t	GetOOCMemoryLimit ()
	Gets the byte limit used for OOC file loading. More...

static size_t	SetOOCMemoryLimit (size_t in_limit_bytes)
	Sets the byte limit used for OOC file loading. More...

static bool	IsDriverAvailable (HPS::Window::Driver in_driver)
	Checks whether the specified driver type is present and available for use. More...

Private Member Functions
	Database ()
	Private default constructor to prevent instantiation. More...

Detailed Description

The Database class is a special type that is never intended to be instantiated.

It contains static functions for creating top-level database objects as well as performing global queries and actions.

Constructor & Destructor Documentation

◆ Database()

HPS::Database::Database ( )

private

Private default constructor to prevent instantiation.

Member Function Documentation

◆ CreateApplicationWindow() [1/2]

static ApplicationWindowKey HPS::Database::CreateApplicationWindow	(	WindowHandle	in_window_handle,
		Window::Driver	in_driver = `Window::Driver::Default3D`
	)

static

Create an application window for the given window handle that Visualize can draw into with the specified driver.

By default Visualize will try to create an anti-alias capable driver.

Parameters

in_window_handle	Handle to the window that Visualize will draw into.
in_driver	Type of driver Visualize should create. Defaults to Window::Driver::Default3D.

Returns: An application window key corresponding to the given handle using the specified driver.

◆ CreateApplicationWindow() [2/2]

static ApplicationWindowKey HPS::Database::CreateApplicationWindow	(	WindowHandle	in_window_handle,
		ApplicationWindowOptionsKit const &	in_options
	)

static

Create an application window for the given window handle that Visualize can draw into with the specified options.

Parameters

in_window_handle	Handle to the window that Visualize will draw into.
in_options	Options for the application window.

Returns: An application window key corresponding to the given handle using the specified options.

◆ CreateEventDispatcher() [1/2]

static EventDispatcher HPS::Database::CreateEventDispatcher ( )

static

Create a new EventDispatcher with a dedicated thread ready to dispatch events to handlers.

Returns: A new EventDispatcher.

◆ CreateEventDispatcher() [2/2]

static EventDispatcher HPS::Database::CreateEventDispatcher ( char const * in_name )

static

Create a new EventDispatcher with a dedicated thread ready to dispatch events to handlers.

Parameters

in_name A specific name for the new dispatcher.

Returns: A new EventDispatcher.

◆ CreateOffScreenWindow() [1/4]

static OffScreenWindowKey HPS::Database::CreateOffScreenWindow	(	unsigned int	in_width,
		unsigned int	in_height,
		Window::Driver	in_driver = `Window::Driver::Default3D`
	)

static

Create an offscreen window of the given height and width with the specified driver.

By default Visualize will try to create an anti-alias capable driver.

Parameters

in_width	Width of the offscreen window in pixels.
in_height	Height of the offscreen window in pixels.
in_driver	Type of driver Visualize should create. Defaults to Window::Driver::Default3D.

Returns: An offscreen window key of the specified size using the specified driver.

◆ CreateOffScreenWindow() [2/4]

static OffScreenWindowKey HPS::Database::CreateOffScreenWindow	(	unsigned int	in_width,
		unsigned int	in_height,
		OffScreenWindowOptionsKit const &	in_options
	)

static

Create an offscreen window of the given height and width with the specified options.

Parameters

in_width	Width of the offscreen window in pixels.
in_height	Height of the offscreen window in pixels.
in_options	Options for the offscreen window.

Returns: An offscreen window key of the specified size using the specified options.

◆ CreateOffScreenWindow() [3/4]

static OffScreenWindowKey HPS::Database::CreateOffScreenWindow	(	ImageDefinition const &	in_destination_image,
		Window::Driver	in_driver = `Window::Driver::Default3D`
	)

static

Create an offscreen window with the specified driver.

By default, Visualize will try to create an anti-alias capable driver.

Parameters

in_destination_image	An RGB or RGBA image definition that the offscreen window will be rendered to.
in_driver	Type of driver Visualize should create. Defaults to Window::Driver::Default3D.

Returns: An offscreen window key of the specified size using the specified driver.

◆ CreateOffScreenWindow() [4/4]

static OffScreenWindowKey HPS::Database::CreateOffScreenWindow	(	ImageDefinition const &	in_destination_image,
		OffScreenWindowOptionsKit const &	in_options
	)

static

Create an offscreen window of the given height and width with the specified options.

Parameters

in_destination_image	An RGB or RGBA image definition that the offscreen window will be rendered to.
in_options	Options for the offscreen window.

Returns: An offscreen window key of the specified size using the specified options.

◆ CreatePortfolio()

static PortfolioKey HPS::Database::CreatePortfolio ( )

static

Create a new portfolio.

Returns: A new portfolio key.

◆ CreateRootSegment()

static SegmentKey HPS::Database::CreateRootSegment ( )

static

Create a new root segment, i.e., a segment without an owner.

Returns: A new root segment key.

◆ CreateStandAloneWindow() [1/2]

static StandAloneWindowKey HPS::Database::CreateStandAloneWindow ( Window::Driver in_driver = Window::Driver::Default3D )

static

Create a stand-alone window with the specified driver.

By default Visualize will try to create an anti-alias capable driver.

Parameters

in_driver Type of driver Visualize should create. Defaults to Window::Driver::Default3D.

Returns: An stand-alone window key using the specified driver.

◆ CreateStandAloneWindow() [2/2]

static StandAloneWindowKey HPS::Database::CreateStandAloneWindow ( StandAloneWindowOptionsKit const & in_options )

static

Create a stand-alone window with the specified options.

Parameters

in_options Options for the stand-alone window.

Returns: An stand-alone window key using the specified options.

◆ Execute()

static void HPS::Database::Execute ( bool in_once = true )

static

This function will pump the stand-alone window event system once by default.

If once is false then the calling thread will loop pumping events and will only return when the last window of any type exits.

Parameters

in_once determines if the stand-alone events are pumped once or forever.

◆ GetErrorEventFilter()

static bool HPS::Database::GetErrorEventFilter ( HPS::Info::Code in_code )

static

Provides the filter state of an ErrorEvent.

Parameters

in_code The info code in to operate on.

Returns: If the specified code is filtered.

◆ GetEventDispatcher()

static EventDispatcher const& HPS::Database::GetEventDispatcher ( )

static

Get the event dispatcher associated with the database.

All database information, errors and warnings will be injected into this EventDispatcher.

Returns: The event dispatcher associated with the database.

◆ GetInformationEventFilter()

static bool HPS::Database::GetInformationEventFilter ( HPS::Info::Code in_code )

static

Provides the filter state of an InformationEvent.

Parameters

in_code The info code in to operate on.

Returns: If the specified code is filtered.

◆ GetMaterialLibraryPortfolio()

static PortfolioKey const HPS::Database::GetMaterialLibraryPortfolio ( )

static

Get the material library portfolio.

This is the portfolio which contains all relevant definitions for materials coming from the material library. It is provided to facilitate importing definitions from this portfolio, or to allow examination of the definitions in the portfolio. It should not be deleted, and if it is, the scene will not render correctly if a file was loaded which depended on the material library.

Returns: The material library portfolio.

◆ GetOOCMemoryLimit()

static size_t HPS::Database::GetOOCMemoryLimit ( )

static

Gets the byte limit used for OOC file loading.

Returns: The current value in bytes.

◆ GetPortfolios()

static PortfolioKeyArray HPS::Database::GetPortfolios ( )

static

Get a list of all portfolios which are active (have been created but not deleted).

Returns: List of all currently active portfolios.

◆ GetRootSegments()

static SegmentKeyArray HPS::Database::GetRootSegments ( )

static

Get a list of all root segments which are active (have been created but not deleted).

Returns: List of all currently active root segments.

◆ GetSoftMemoryLimit()

static size_t HPS::Database::GetSoftMemoryLimit ( )

static

Gets the value at which the EmergencyHandler will be activated for SoftMemoryLimit.

Returns: The current value in bytes.

◆ GetTime()

static Time HPS::Database::GetTime ( )

static

Queries the number of milliseconds that have elapsed since Visualize started.

Returns: The number of milliseconds that have elapsed since Visualize started.

◆ GetWarningEventFilter()

static bool HPS::Database::GetWarningEventFilter ( HPS::Info::Code in_code )

static

Provides the filter state of a WarningEvents.

Parameters

in_code The info code in to operate on.

Returns: If the specified code is filtered.

◆ GetWindowKeys()

static WindowKeyArray HPS::Database::GetWindowKeys ( )

static

Get a list of all windows (application, stand-alone, and offscreen) which are active (have been created but not deleted).

Returns: List of all currently active windows.

◆ IsDriverAvailable()

static bool HPS::Database::IsDriverAvailable ( HPS::Window::Driver in_driver )

static

Checks whether the specified driver type is present and available for use.

Parameters

in_driver the driver type to check availability for.

Returns: Whether the driver is available or not.

◆ RelinquishMemory()

static void HPS::Database::RelinquishMemory ( )

static

Relinquish any internally cached memory to the system.

This can reduce performance and stability if overused. If your application inserts or removes items from the Visualize database continuously, this function should not be used, even as a means of 'obtaining more memory' for the application. Otherwise, Visualize will simply allocate more memory from the operating system. This is slower than using its built in memory manager to allocate from its currently available memory pool. However, if you have a case where database interactions have perhaps reached a point of stabilization (for example, a model is loaded and has been interacted with already, and no other operations are going to incur extra memory usage), this function could prove useful by having Visualize free up its unused portion of allocated memory.

This function should generally not be called on 32-bit Windows operating systems, because it can significantly shorten the life of an application. When memory is freed back to the system on 32-bit Windows, the real memory gets freed and defragmented by the OS, but the virtual address space does not. If an application keeps allocating and freeing system memory during its lifetime, memory will run out due to the address space fragmentation, even though physical memory might still be available. While 64-bit systems do not have the 'virtual address space fragmentation' issue, you typically should avoid calling this method, and rely on Visualize to manage its allocated memory during the lifetime of your application.

Note that you can track Visualize's current memory usage by calling HPS::Database::ShowMemoryUsage.

◆ Reset()

static void HPS::Database::Reset ( )

static

Performs a complete reset of the Visualize database.

All segments are deleted and all window displays are terminated. This will leave all keys, controls, and dispatchers invalid. Kits are preserved. This can never be called from inside an event handler.

It may be appropriate to call this method if your application doesn't need to use Visualize for a while.

◆ SelectByRay()

static size_t HPS::Database::SelectByRay	(	Point const &	in_start_point,
		Vector const &	in_direction,
		SelectionOptionsKit const &	in_options,
		SelectionResults &	out_results
	)

static

Performs an object space selection by ray starting at the specified segment using the specified selection options.

This method can only select faceted geometry.

Parameters

in_start_point	Start point of ray.
in_direction	Direction vector for ray.
in_options	Selection options to use when performing the selection.
out_results	Results of the selection.

Returns: Number of selected items.

◆ SelectByShell() [1/2]

static size_t HPS::Database::SelectByShell	(	ShellKit const &	in_shell,
		SelectionOptionsKit const &	in_options,
		SelectionResults &	out_results
	)

static

Performs an object space selection by shell starting at the specified segment using the specified selection options.

This method can only select faceted geometry.

Parameters

in_shell	Shell to use to perform the selection.
in_options	Selection options to use when performing the selection.
out_results	Results of the selection.

Returns: Number of selected items.

◆ SelectByShell() [2/2]

static size_t HPS::Database::SelectByShell	(	ShellKey const &	in_shell,
		SelectionOptionsKit const &	in_options,
		SelectionResults &	out_results
	)

static

Performs an object space selection by shell starting at the specified segment using the specified selection options.

This method can only select faceted geometry.

Parameters

in_shell	Shell in the database to use to perform the selection.
in_options	Selection options to use when performing the selection.
out_results	Results of the selection.

Returns: Number of selected items.

◆ SelectByVolume()

static size_t HPS::Database::SelectByVolume	(	SimpleCuboid const &	in_volume,
		SelectionOptionsKit const &	in_options,
		SelectionResults &	out_results
	)

static

Performs an object space selection by volume starting at the specified segment using the specified selection options.

If the volume is invalid, i.e., min > max for any component, an exception will be thrown.

Parameters

in_volume	Volume to use when performing the selection.
in_options	Selection options to use when performing the selection.
out_results	Results of the selection.

Returns: Number of selected items.

◆ SetEmergencyHandler()

static void HPS::Database::SetEmergencyHandler ( HPS::EmergencyHandler const & in_emergency_handler )

static

Sets a custom EmergencyHandler.

Parameters

in_emergency_handler The EmergencyHandler to use.

◆ SetErrorEventFilter()

static bool HPS::Database::SetErrorEventFilter	(	HPS::Info::Code	in_code,
		bool	in_filtered
	)

static

Sets if a specific code for ErrorEvent should be filtered.

Parameters

in_code	The info code in to operate on.
in_filtered	The new filter state desired.

Returns: The old value for the specified code.

◆ SetInformationEventFilter()

static bool HPS::Database::SetInformationEventFilter	(	HPS::Info::Code	in_code,
		bool	in_filtered
	)

static

Sets if a specific code for InformationEvent should be filtered.

Parameters

in_code	The info code in to operate on.
in_filtered	The new filter state desired.

Returns: The old value for the specified code.

◆ SetOOCMemoryLimit()

static size_t HPS::Database::SetOOCMemoryLimit ( size_t in_limit_bytes )

static

Sets the byte limit used for OOC file loading.

A limit of zero bytes restores the default value.

Parameters

in_limit_bytes The new limit value in bytes.

Returns: The old value in bytes.

◆ SetSoftMemoryLimit()

static size_t HPS::Database::SetSoftMemoryLimit ( size_t in_limit_bytes )

static

Sets the value at which the EmergencyHandler will be activated for SoftMemoryLimit.

Parameters

in_limit_bytes The new limit value in bytes.

Returns: The old value in bytes.

◆ SetWarningEventFilter()

static bool HPS::Database::SetWarningEventFilter	(	HPS::Info::Code	in_code,
		bool	in_filtered
	)

static

Sets if a specific code for WarningEvent should be filtered.

Parameters

in_code	The info code in to operate on.
in_filtered	The new filter state desired.

Returns: The old value for the specified code.

◆ ShowMemoryUsage()

static void HPS::Database::ShowMemoryUsage	(	size_t &	out_allocated,
		size_t &	out_used
	)

static

Returns information about system memory usage.

It may be useful to know how much memory Visualize is using to store graphical information. Visualize utilizes its own internal memory manager. It generally allocates memory in large chunks from the operating system, then parcels the chunks out as needed by the database. Upon entity deletion, Visualize will keep some cached information, as well as the chunks of memory associated with the deleted items, effectively 'recycling' them. Allocated memory indicates the total size of all chunks; used memory indicates the amount that's currently parceled out.

The memory usage information is also useful during debugging - you might be able to use it to determine if your program (or perhaps Visualize) is "leaking" memory - for example, not cleaning up the segment tree properly after a procedure is finished.

Some changes and deletions in the database might cause immediate changes in the memory usage statistics, while others might be delayed until after the next update.

Because of the nature of Visualize's built-in memory allocation methods, only a call to HPS::Database::RelinquishMemory or HPS::Database::Reset can clean up memory that has been allocated but not used and return it to the operating system. However, HPS::Database::RelinquishMemory should be used with care, so be sure to review the documentation.

\param out_allocated    Total bytes currently allocated from the OS.
\param out_used         Total bytes currently in use by the database.

◆ Sleep()

static void HPS::Database::Sleep ( Time milliseconds )

static

Sleep for the number of milliseconds requested.

◆ Synchronize()

static void HPS::Database::Synchronize ( )

static

Synchronizes the database, guaranteeing that all queued actions and updates have been performed.

◆ UnsetEmergencyHandler()

static void HPS::Database::UnsetEmergencyHandler ( )

static

Sets the default EmergencyHandler.

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

hps.h

Static Public Member Functions

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Database()

Member Function Documentation

◆ CreateApplicationWindow() [1/2]

◆ CreateApplicationWindow() [2/2]

◆ CreateEventDispatcher() [1/2]

◆ CreateEventDispatcher() [2/2]

◆ CreateOffScreenWindow() [1/4]

◆ CreateOffScreenWindow() [2/4]

◆ CreateOffScreenWindow() [3/4]

◆ CreateOffScreenWindow() [4/4]

◆ CreatePortfolio()

◆ CreateRootSegment()

◆ CreateStandAloneWindow() [1/2]

◆ CreateStandAloneWindow() [2/2]

◆ Execute()

◆ GetErrorEventFilter()

◆ GetEventDispatcher()

◆ GetInformationEventFilter()

◆ GetMaterialLibraryPortfolio()

◆ GetOOCMemoryLimit()

◆ GetPortfolios()

◆ GetRootSegments()

◆ GetSoftMemoryLimit()

◆ GetTime()

◆ GetWarningEventFilter()

◆ GetWindowKeys()

◆ IsDriverAvailable()

◆ RelinquishMemory()

◆ Reset()

◆ SelectByRay()

◆ SelectByShell() [1/2]

◆ SelectByShell() [2/2]

◆ SelectByVolume()

◆ SetEmergencyHandler()

◆ SetErrorEventFilter()

◆ SetInformationEventFilter()

◆ SetOOCMemoryLimit()

◆ SetSoftMemoryLimit()

◆ SetWarningEventFilter()

◆ ShowMemoryUsage()

◆ Sleep()

◆ Synchronize()

◆ UnsetEmergencyHandler()