OS and processor abstraction. More...

Public Types
typedef bool(*	OutOfMemoryCallback) (size_t size, bool recoverable)

Static Public Member Functions
static void	alignedFree (void *ptr)
	Frees memory allocated with alignedMalloc. More...

static void *	alignedMalloc (size_t bytes, size_t alignment)
	Guarantees that the start of the array is aligned to the specified number of bytes. More...

static String &	appName ()
	Name of this program. More...

static const String &	build ()
	The optimization status of the G3D library (not the program compiled against it) More...

static void *	calloc (size_t n, size_t x)

static void	cleanup ()
	atexit handling code invoked from G3DCleanupHook. More...

static void	consoleClearScreen ()
	Clears the console. More...

static bool	consoleKeyPressed ()
	Returns true if a key is waiting. More...

static int	consoleReadKey ()
	Blocks until a key is read (use consoleKeyPressed to determine if a key is waiting to be read) then returns the character code for that key. More...

static const String &	cpuArchitecture ()
	e.g., 80686 More...

static String	currentDateString ()
	Returns the current date as a string in the form YYYY-MM-DD. More...

static String	currentProgramFilename ()
	Returns the fully qualified filename for the currently running executable. More...

static String	currentTimeString ()
	Returns the current 24-hour local time as a string in the form HH:MM:SS. More...

static void	describeSystem (class TextOutput &t)
	Prints a human-readable description of this machine to the text output stream. More...

static void	describeSystem (String &s)

static String	findDataFile (const String &full, bool exceptionIfNotFound=true, bool caseSensitive=false)
	Tries to locate the resource by looking in related directories. More...

static void	free (void *p)
	Free data allocated with System::malloc. More...

static const String &	g3dRevision ()
	Source control revision of G3D build. More...

static const char *	getEnv (const String &name)
	Get an environment variable for the current process. More...

static void	getG3DDataPaths (std::vector< String > &paths)
	Appends search paths specified by G3D10DATA environment variable to paths vector, since cannot rely on Array. More...

static void	initializeDirectoryArray (Array< String, 10 > &directoryArray, bool caseSensitive=false)

static G3DEndian	machineEndian ()
	Returns the endianness of this machine. More...

static void *	malloc (size_t bytes)
	Uses pooled storage to optimize small allocations (1 byte to 5 kilobytes). More...

static String	mallocStatus ()
	Returns a string describing the current usage of the buffer pools used for optimizing System::malloc, and describing how well System::malloc is using its internal pooled storage. More...

static void	memcpy (void dst, const void src, size_t numBytes)
	An implementation of memcpy that may be up to 2x as fast as the C library one on some processors. More...

static void	memset (void *dst, uint8 value, size_t numBytes)
	An implementation of memset that may be up to 2x as fast as the C library one on some processors. More...

static const String &	operatingSystem ()
	e.g., "Windows", "GNU/Linux" More...

static OutOfMemoryCallback	outOfMemoryCallback ()
	When System::malloc fails to allocate memory because the system is out of memory, it invokes this handler (if it is not nullptr). More...

static void *	realloc (void *block, size_t bytes)
	Version of realloc that works with System::malloc. More...

static void	resetMallocPerformanceCounters ()

static void	setAppDataDir (const String &path)
	Sets the path that the application is using as its data directory. More...

static void	setAppDataDirs (const std::vector< String > &paths)
	Sets additional paths that the application will search for data files. More...

static void	setEnv (const String &name, const String &value)
	Set an environment variable for the current process. More...

static void	setOutOfMemoryCallback (OutOfMemoryCallback c)

static void	sleep (RealTime t)
	Causes the current thread to yield for the specified duration and consume almost no CPU. More...

static RealTime	time ()
	The actual time (measured in seconds since Jan 1 1970 midnight). More...

static const String &	version ()
	G3D Version string. More...

Detailed Description

OS and processor abstraction.

The first time any method is called the processor will be analyzed. Future calls are then fast.

Member Typedef Documentation

◆ OutOfMemoryCallback

typedef bool(* G3D::System::OutOfMemoryCallback) (size_t size, bool recoverable)

Parameters

size	Size of memory that the system was trying to allocate
recoverable	If true, the system will attempt to allocate again if the callback returns true. If false, malloc is going to return nullptr and this invocation is just to notify the application.

Returns: Return true to force malloc to attempt allocation again if the error was recoverable.

Member Function Documentation

◆ alignedFree()

static void G3D::System::alignedFree ( void * ptr )

static

Frees memory allocated with alignedMalloc.

◆ alignedMalloc()

static void* G3D::System::alignedMalloc	(	size_t	bytes,
		size_t	alignment
	)

static

Guarantees that the start of the array is aligned to the specified number of bytes.

◆ appName()

static String& G3D::System::appName ( )

static

Name of this program.

Note that you can mutate this string to set your app name explicitly.

◆ build()

static const String& G3D::System::build ( )

static

The optimization status of the G3D library (not the program compiled against it)

Either "Debug" or "Release", depending on whether _DEBUG was defined at compile-time for the library.

◆ calloc()

static void* G3D::System::calloc	(	size_t	n,
		size_t	x
	)

static

◆ cleanup()

static void G3D::System::cleanup ( )

static

atexit handling code invoked from G3DCleanupHook.

◆ consoleClearScreen()

static void G3D::System::consoleClearScreen ( )

static

Clears the console.

Console programs only.

◆ consoleKeyPressed()

static bool G3D::System::consoleKeyPressed ( )

static

Returns true if a key is waiting.

Console programs only.

◆ consoleReadKey()

static int G3D::System::consoleReadKey ( )

static

Blocks until a key is read (use consoleKeyPressed to determine if a key is waiting to be read) then returns the character code for that key.

◆ cpuArchitecture()

static const String& G3D::System::cpuArchitecture ( )

inlinestatic

e.g., 80686

◆ currentDateString()

static String G3D::System::currentDateString ( )

static

Returns the current date as a string in the form YYYY-MM-DD.

◆ currentProgramFilename()

static String G3D::System::currentProgramFilename ( )

static

Returns the fully qualified filename for the currently running executable.

This is more reliable than arg[0], which may be intentionally set to an incorrect value by a calling program, relative to a now non-current directory, or obfuscated by sym-links.

Referenced Code: Linux version written by Nicolai Haehnle <prefect_.net>, http://www.flipcode.com/cgi-bin/msg.cgi?showThread=COTD-getexename&forum=cotd&id=-1

◆ currentTimeString()

static String G3D::System::currentTimeString ( )

static

Returns the current 24-hour local time as a string in the form HH:MM:SS.

◆ describeSystem() [1/2]

static void G3D::System::describeSystem ( class TextOutput & t )

static

Prints a human-readable description of this machine to the text output stream.

Either argument may be nullptr.

◆ describeSystem() [2/2]

static void G3D::System::describeSystem ( String & s )

static

◆ findDataFile()

static String G3D::System::findDataFile	(	const String &	full,
		bool	exceptionIfNotFound = `true`,
		bool	caseSensitive = `false`
	)

static

Tries to locate the resource by looking in related directories.

If found, returns the full path to the resource, otherwise returns the empty string.

Looks in:

- Literal interpretation of full (i.e., if it contains a fully-qualified name)
- Last directory in which a file was found
- Current directory
- System::appDataDir (which is usually GApp::Settings.dataDir, which defaults to the directory containing the program binary)
- System::appDataDir() + "data/"  (note that this may be a zipfile named "data" with no extension)
- System::appDataDir() + "data.zip/"
- ../data-files/ 
- ../../data-files/
- ../../../data-files/
- $G3D10DATA directories. This must be a semicolon (windows) or colon (OS X/Linux) separated list of paths. It may be a single path.

Plus the following subdirectories of those:

cubemap
gui
font
icon
models
image
sky
md2
md3
ifs
3ds

Parameters

exceptionIfNotFound If true and the file is not found, throws G3D::FileNotFound.

Referenced by G3D::EmulatedXR::EmulatedXRController::modelFilename().

◆ free()

static void G3D::System::free ( void * p )

static

Free data allocated with System::malloc.

Threadsafe on Win32.

Referenced by G3D::Queue< G3D::_internal::NetworkCallbackInfo >::clear(), G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::clear(), G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::grow(), G3D::UniversalSurface::operator delete(), G3D::Matrix::Impl::operator delete(), G3D::UniversalSurfel::operator delete(), G3D::UniversalSurface::GPUGeom::operator delete(), G3D::HeightfieldModel::Tile::operator delete(), and G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::~FastPODTable().

◆ g3dRevision()

static const String& G3D::System::g3dRevision ( )

inlinestatic

Source control revision of G3D build.

◆ getEnv()

static const char* G3D::System::getEnv ( const String & name )

static

Get an environment variable for the current process.

Returns nullptr if the variable doesn't exist.

◆ getG3DDataPaths()

static void G3D::System::getG3DDataPaths ( std::vector< String > & paths )

static

Appends search paths specified by G3D10DATA environment variable to paths vector, since cannot rely on Array.

◆ initializeDirectoryArray()

static void G3D::System::initializeDirectoryArray	(	Array< String, 10 > &	directoryArray,
		bool	caseSensitive = `false`
	)

static

◆ machineEndian()

static G3DEndian G3D::System::machineEndian ( )

inlinestatic

Returns the endianness of this machine.

◆ malloc()

static void* G3D::System::malloc ( size_t bytes )

static

Uses pooled storage to optimize small allocations (1 byte to 5 kilobytes).

Can be 10x to 100x faster than calling malloc or new.

The result must be freed with free.

Threadsafe on Win32.

See also: calloc realloc OutOfMemoryCallback free

Referenced by G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::clear(), G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::FastPODTable(), G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::grow(), G3D::UniversalSurface::operator new(), G3D::Matrix::Impl::operator new(), G3D::UniversalSurfel::operator new(), G3D::UniversalSurface::GPUGeom::operator new(), and G3D::HeightfieldModel::Tile::operator new().

◆ mallocStatus()

static String G3D::System::mallocStatus ( )

static

Returns a string describing the current usage of the buffer pools used for optimizing System::malloc, and describing how well System::malloc is using its internal pooled storage.

"heap" memory was slow to allocate; the other data sizes are comparatively fast.

◆ memcpy()

static void G3D::System::memcpy	(	void *	dst,
		const void *	src,
		size_t	numBytes
	)

static

An implementation of memcpy that may be up to 2x as fast as the C library one on some processors.

Guaranteed to have the same behavior as memcpy in all cases.

Referenced by G3D::Array< G3D::AABox >::appendPOD(), G3D::Array< G3D::AABox >::copyPOD(), G3D::MD5Hash::rotateBytes(), G3D::AttributeArray::updateInterleaved(), and G3D::BinaryOutput::writeBytes().

◆ memset()

static void G3D::System::memset	(	void *	dst,
		uint8	value,
		size_t	numBytes
	)

static

An implementation of memset that may be up to 2x as fast as the C library one on some processors.

Guaranteed to have the same behavior as memset in all cases.

Referenced by G3D::MD2Model::Pose::Action::Action(), G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::clear(), G3D::_BSPMAP::BitSet::clearAll(), G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::fastClear(), G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::FastPODTable(), and G3D::FastPODTable< Key, Value, HashFunc, EqualsFunc, valueIsSimplePOD >::grow().

◆ operatingSystem()

static const String& G3D::System::operatingSystem ( )

inlinestatic

e.g., "Windows", "GNU/Linux"

◆ outOfMemoryCallback()

static OutOfMemoryCallback G3D::System::outOfMemoryCallback ( )

inlinestatic

When System::malloc fails to allocate memory because the system is out of memory, it invokes this handler (if it is not nullptr).

The argument to the callback is the amount of memory that malloc was trying to allocate when it ran out. If the callback returns true, System::malloc will attempt to allocate the memory again. If the callback returns false, then System::malloc will return nullptr.

You can use outOfMemoryCallback to free data structures or to register the failure.

◆ realloc()

static void* G3D::System::realloc	(	void *	block,
		size_t	bytes
	)

static

Version of realloc that works with System::malloc.

◆ resetMallocPerformanceCounters()

static void G3D::System::resetMallocPerformanceCounters ( )

static

◆ setAppDataDir()

static void G3D::System::setAppDataDir ( const String & path )

static

Sets the path that the application is using as its data directory.

Used by findDataDir as an initial search location. GApp sets this upon constrution.

◆ setAppDataDirs()

static void G3D::System::setAppDataDirs ( const std::vector< String > & paths )

static

Sets additional paths that the application will search for data files.

Used by findDataDir as an search locations. GApp sets this upon constrution.

◆ setEnv()

static void G3D::System::setEnv	(	const String &	name,
		const String &	value
	)

static

Set an environment variable for the current process.

◆ setOutOfMemoryCallback()

static void G3D::System::setOutOfMemoryCallback ( OutOfMemoryCallback c )

inlinestatic

◆ sleep()

static void G3D::System::sleep ( RealTime t )

static

Causes the current thread to yield for the specified duration and consume almost no CPU.

The sleep will be extremely precise; it uses System::time() to calibrate the exact yeild time.

◆ time()

static RealTime G3D::System::time ( )

static

The actual time (measured in seconds since Jan 1 1970 midnight).

Adjusted for local timezone and daylight savings time. This is as accurate and fast as getCycleCount().

Referenced by G3D::Entity::markChanged(), G3D::Light::setEnabled(), G3D::Light::setShadowsEnabled(), and G3D::_internal::Morph::update().

◆ version()

static const String& G3D::System::version ( )

inlinestatic

G3D Version string.

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ OutOfMemoryCallback

Member Function Documentation

◆ alignedFree()

◆ alignedMalloc()

◆ appName()

◆ build()

◆ calloc()

◆ cleanup()

◆ consoleClearScreen()

◆ consoleKeyPressed()

◆ consoleReadKey()

◆ cpuArchitecture()

◆ currentDateString()

◆ currentProgramFilename()

◆ currentTimeString()

◆ describeSystem() [1/2]

◆ describeSystem() [2/2]

◆ findDataFile()

◆ free()

◆ g3dRevision()

◆ getEnv()

◆ getG3DDataPaths()

◆ initializeDirectoryArray()

◆ machineEndian()

◆ malloc()

◆ mallocStatus()

◆ memcpy()

◆ memset()

◆ operatingSystem()

◆ outOfMemoryCallback()

◆ realloc()

◆ resetMallocPerformanceCounters()

◆ setAppDataDir()

◆ setAppDataDirs()

◆ setEnv()

◆ setOutOfMemoryCallback()

◆ sleep()

◆ time()

◆ version()