PixelLightAPI  .
Public Types | Static Public Member Functions
PLCore::Runtime Class Reference

PixelLight framework runtime class. More...

#include <Runtime.h>

List of all members.

Public Types

enum  EType { StaticInstallation, LocalInstallation, SystemInstallation }
 Runtime installation type. More...

Static Public Member Functions

static PLCORE_API EType GetType ()
 Get used PixelLight installation type.
static PLCORE_API Version GetVersion ()
 Get PixelLight version.
static bool IsDebugVersion ()
 Return whether or not this is a debug version of PixelLight.
static PLCORE_API String GetSuffix ()
 Get PixelLight suffix.
static String GetLocalDirectory ()
 Try to find the local PixelLight runtime directory.
static PLCORE_API String GetLocalDataDirectory ()
 Try to find the local PixelLight runtime data directory.
static PLCORE_API String GetSystemDirectory ()
 Try to find the system PixelLight runtime directory.
static PLCORE_API String GetSystemDataDirectory ()
 Try to find the system PixelLight runtime data directory.
static PLCORE_API String GetRegistryDirectory ()
 Try to find the system PixelLight runtime directory by reading the registry.
static PLCORE_API String GetRegistryDataDirectory ()
 Try to find the system PixelLight runtime data directory by reading the registry.
static PLCORE_API String GetDirectory ()
 Try to find the PixelLight runtime directory used by the running process.
static PLCORE_API String GetDataDirectory ()
 Try to find the PixelLight runtime data directory used by the running process.
static PLCORE_API String GetPLCoreSharedLibraryName ()
 Returns the name of the PLCore shared library.
static PLCORE_API String GetPLCoreSharedLibraryDirectory ()
 Returns the absolute path to the directory the PLCore shared library is in.
static PLCORE_API bool SetDirectory (const String &sDirectory, String *pszErrorMessage=nullptr)
 Sets the given PixelLight runtime directory.
static PLCORE_API void ScanDirectoryPlugins (const String &sDirectory="", bool bDelayedPluginLoading=true)
 Scan system PixelLight runtime directory for compatible plugins and load them in.
static PLCORE_API void ScanDirectoryData (const String &sDirectory="")
 Scan system PixelLight runtime directory for compatible data and register it.
static PLCORE_API bool ScanDirectoryPluginsAndData (bool bUrgentMessageAllowed=true)
 Scan PixelLight runtime directory for compatible plugins and load them in as well as scan for compatible data and register it.

Detailed Description

PixelLight framework runtime class.

Note:
  • There can be a local and system runtime at the same time, although this is not recommended
  • On Windows 64 bit it's possible to have a 32 bit and a 64 bit PixelLight runtime version installed at the same time (even in the PATH environment variable, the OS will automatically pick the correct dll)

Member Enumeration Documentation

Runtime installation type.

Enumerator:
StaticInstallation 

The running process is using the static linked version of PLCore

LocalInstallation 

The PixelLight runtime is in the same directory as the running process, making this to a local installation

SystemInstallation 

The PixelLight runtime is registered within the system, making this to a system installation


Member Function Documentation

static PLCORE_API EType PLCore::Runtime::GetType ( ) [static]

Get used PixelLight installation type.

Returns:
Used PixelLight installation type the running process is using
static PLCORE_API Version PLCore::Runtime::GetVersion ( ) [static]

Get PixelLight version.

Returns:
Version of this PixelLight installation the running process is using
bool PLCore::Runtime::IsDebugVersion ( ) [inline, static]

Return whether or not this is a debug version of PixelLight.

Returns:
'true' if the running process is using a debug version of PixelLight, else 'false'
static PLCORE_API String PLCore::Runtime::GetSuffix ( ) [static]

Get PixelLight suffix.

Returns:
Suffix of this PixelLight installation the running process is using

Try to find the local PixelLight runtime directory.

Returns:
Path to the local PixelLight runtime directory (e.g. "file://C:/MyApplication/x86" on Windows), or ""
static PLCORE_API String PLCore::Runtime::GetLocalDataDirectory ( ) [static]

Try to find the local PixelLight runtime data directory.

Returns:
Path to the local PixelLight runtime data directory (e.g. "file://C:/MyApplication/Data" on Windows), or ""
static PLCORE_API String PLCore::Runtime::GetSystemDirectory ( ) [static]

Try to find the system PixelLight runtime directory.

Returns:
Path to the system PixelLight runtime directory (e.g. "file://C:/PixelLight/Runtime/x86" on Windows), or ""
static PLCORE_API String PLCore::Runtime::GetSystemDataDirectory ( ) [static]

Try to find the system PixelLight runtime data directory.

Returns:
Path to the system PixelLight runtime data directory (e.g. "file://C:/PixelLight/Runtime/Data" on Windows), or ""
static PLCORE_API String PLCore::Runtime::GetRegistryDirectory ( ) [static]

Try to find the system PixelLight runtime directory by reading the registry.

Returns:
Path to the system PixelLight runtime directory (e.g. "file://C:/PixelLight/Runtime/x86" on Windows), or ""
Remarks:
For this method, you also need to add a key to the registry (or environment, depending on the used OS, in here the MS Windows terminology is used), so that the path to the build PixelLight runtime can be found during runtime. This means that there's a high probability that this registry key does not exist or it's configuration is invalid. So, if you don't really need this method, try to avoid using it to reduce possible errors. When e.g. using a static build of PLCore, this registry method has to be used in order to be able to find the system PixelLight runtime directory.

On MS Windows, this key has to be at "HKEY_LOCAL_MACHINE/SOFTWARE/PixelLight/PixelLight-SDK/Runtime" (or at "HKEY_LOCAL_MACHINE/SOFTWARE/Wow6432Node/PixelLight/PixelLight-SDK/Runtime" if you are using a 32 bit PixelLight SDK on a 64 bit MS Windows). This "Runtime"-key has e.g. the string value "C:/PixelLight/Bin/Runtime/x86/" (same as the PATH environment variable entry pointing to the PixelLight runtime directory).

On Linux, the "PL_RUNTIME" environment variable is used. If this variable does not exist, "/usr/local/share/pixellight/Runtime" will be used, if it exists.

See also:
static PLCORE_API String PLCore::Runtime::GetRegistryDataDirectory ( ) [static]

Try to find the system PixelLight runtime data directory by reading the registry.

Returns:
Path to the system PixelLight runtime data directory (e.g. "file://C:/PixelLight/Runtime/Data" on Windows), or ""
See also:
  • "GetRegistryDirectory()"
static PLCORE_API String PLCore::Runtime::GetDirectory ( ) [static]

Try to find the PixelLight runtime directory used by the running process.

Returns:
Path to the PixelLight runtime directory used by the running process (e.g. "file://C:/MyApplication/x86" or "file://C:/PixelLight/Runtime/x86" etc. on Windows), or ""
Remarks:
As soon as an application executable is started and therefore has become a running process, it's bound to a certain PixelLight runtime. Usually, an OS will first search for required shared libraries within the same directory the application executable is in. If the PLCore shared library was found within the application executable directory, this means that a local PixelLight runtime is used. Of course, there can be a local and system PixelLight runtime at the same time (although this is not recommended), but this still means, that in the described situation, the local PLCore shared library is used and therefore the local PixelLight runtime. The "GetDirectory()"-method returns the PixelLight runtime used by the running process. This means that internally "GetLocalDirectory()" is called at first and if this method returns an empty string, a "GetSystemDirectory()" call follows in exactly this order.
static PLCORE_API String PLCore::Runtime::GetDataDirectory ( ) [static]

Try to find the PixelLight runtime data directory used by the running process.

Returns:
Path to the PixelLight runtime data directory used by the running process (e.g. "file://C:/MyApplication/Data" or "file://C:/PixelLight/Runtime/Data" etc. on Windows), or ""
See also:
static PLCORE_API String PLCore::Runtime::GetPLCoreSharedLibraryName ( ) [static]

Returns the name of the PLCore shared library.

Returns:
The name of the PLCore shared library (e.g. "libPLCore.so" or "PLCoreD.dll")

Returns the absolute path to the directory the PLCore shared library is in.

Returns:
The absolute path to the directory the PLCore shared library is in (e.g. "file://C:/PixelLight/Runtime/x86" on Windows), empty string on error
static PLCORE_API bool PLCore::Runtime::SetDirectory ( const String sDirectory,
String pszErrorMessage = nullptr 
) [static]

Sets the given PixelLight runtime directory.

Parameters:
[in]sDirectoryPath to the PixelLight runtime directory (e.g. "C:\PixelLight\Runtime\x86" on Windows), or ""
[out]pszErrorMessageIf this parameter is no null pointer and there was an error, this string will receive a human readable error description, if there was no error this string is not touched
Returns:
Returns 'true' if all went fine, else 'false'
See also:
  • "GetDirectory()"
static PLCORE_API void PLCore::Runtime::ScanDirectoryPlugins ( const String sDirectory = "",
bool  bDelayedPluginLoading = true 
) [static]

Scan system PixelLight runtime directory for compatible plugins and load them in.

Parameters:
[in]sDirectoryDirectory to use (for example the result of "GetDirectory()", "GetLocalDirectory()" or "GetSystemDirectory()"), if empty string the result of "GetDirectory()" will be used
[in]bDelayedPluginLoading'true' if it's allowed to perform delayed shared library loading to speed up the program start, else 'false'
Remarks:
The implementation does the following tasks:
  • Scan for plugins in PixelLight runtime directory non-recursively
See also:
static PLCORE_API void PLCore::Runtime::ScanDirectoryData ( const String sDirectory = "") [static]

Scan system PixelLight runtime directory for compatible data and register it.

Parameters:
[in]sDirectoryDirectory to use (for example the result of "GetDataDirectory()", "GetLocalDataDirectory()" or "GetSystemDataDirectory()"), if empty string the result of "GetDataDirectory()" will be used
Remarks:
The implementation does the following tasks:
  • Add PixelLight runtime directory "Data/" as a base directory to the loadable manager
  • Scan for data in PixelLight runtime directory "Data/"
See also:
static PLCORE_API bool PLCore::Runtime::ScanDirectoryPluginsAndData ( bool  bUrgentMessageAllowed = true) [static]

Scan PixelLight runtime directory for compatible plugins and load them in as well as scan for compatible data and register it.

Parameters:
[in]bUrgentMessageAllowedIs this method allowed to show an urgent message to the user in case of a failure?
Returns:
'true' if all went fine, else 'false'
Remarks:
In case you don't care about technical details and just want the stuff runnable, then just call this method and be happy. The PixelLight runtime to use is detected automatically, all available compatible plugins are registered as well as compatible data.
See also:

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


PixelLight PixelLight 0.9.11-R1
Copyright (C) 2002-2012 by The PixelLight Team
Last modified Thu Feb 23 2012 14:09:26
The content of this PixelLight document is published under the
Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported