Platform_OS Class Reference
[Platform]

Platform independent abstraction of common OS functionality. More...

Inheritance diagram for Platform_OS:

List of all members.

Public Member Functions
virtual	~Platform_OS ()
virtual void	SetApplicationName (const char *applicationName)=0
virtual const char *	GetCommandLineString ()=0
virtual const char *	GetExecutablePath ()=0
virtual bool	HasFocus ()=0
virtual void	OsYield ()=0
virtual void	DisplayAssertMessage (const char *expression, const char *message, const char *file, int line)=0
virtual void	OutputDebugText (const char *formatstr,...)=0
virtual void	ReportFatalError (const char *message, const char *file, int line)=0
virtual bool	ExitRequested ()=0

---

Detailed Description

Platform independent abstraction of common OS functionality.

Author:

Mattias Gustavsson

Platform_OS is a system wich will be in use on all platforms. This is where the main window and message pump is handled under Windows, and similar things is done for other platforms. It implements various OS specific, basic functionality.

Definition at line 23 of file Platform_OS.h.

---

Constructor & Destructor Documentation

virtual Platform_OS::~Platform_OS

(

)

[virtual]

Destructor

Definition at line 29 of file Platform_OS.h.

---

Member Function Documentation

virtual void Platform_OS::SetApplicationName

(

const char *

applicationName

)

[pure virtual]

Sets the name of the application. This is what's displayed in the title bar of the window, if the current platform has a window. On some platforms, this method will have no effect, but it can still be called with no error. If 0 is passed to the method, the default name "Pixie Game Engine" will be used.

Parameters:

applicationName

The name of the application, or 0 for default name

Implemented in Platform_NULL_OS, and Platform_Win32_OS.

virtual const char* Platform_OS::GetCommandLineString

(

)

[pure virtual]

If the platform supports command line parameters, and some were passed in to the application, they can be retrieved using this method. The platform specific implementation may reformat the original command line strings, such that all flags will have a dash (-) as a prefix, that long filenames containing spaces will be surrounded by quotation marks (") and that directory separators for specified paths will be forward slash (/) regardless of whatever convention was originally used on the platform. This is to make it easy to parse the command line string without knowing which platform we're currently running on.

Returns:

The command line string in platform independent format

Implemented in Platform_NULL_OS, and Platform_Win32_OS.

virtual const char* Platform_OS::GetExecutablePath

(

)

[pure virtual]

Sometimes, it's useful to find the path where the applications executable is stored, in case it is different from the current working directory. This method will return the full path to the executable, not including the name of the executable itself. On some platforms, this information might not be available, in which case this method will return 0.

Returns:

The path to the executable

Implemented in Platform_NULL_OS, and Platform_Win32_OS.

virtual bool Platform_OS::HasFocus

(

)

[pure virtual]

For windowed systems, it is possible for the app to not be the one currently receiving input. This method will return true if the application has input focus, and false if it has not. On non-windowed platforms, this method will always return true.

Returns:

True if the application has focus, false if it has not.

Implemented in Platform_NULL_OS, and Platform_Win32_OS.

virtual void Platform_OS::OsYield

(

)

[pure virtual]

On some platforms, it is necessary to hand control over to the OS at regular intervals (typically once per frame), for example the windows message pump. This method should be called by the game once per frame, but on some platforms, it might not do anything, while on others it might do a lot.

Not calling this method might lead to unresponsive application or unexpected side effects. When called, this method sends the "OsYield" platform event, which will be received by all platform systems which have registered for platform events.

Implemented in Platform_NULL_OS, and Platform_Win32_OS.

virtual void Platform_OS::DisplayAssertMessage	(	const char *	expression,
		const char *	message,
		const char *	file,
		int	line
	)			[pure virtual]

The way Assert failures are reported is different on different platforms. On some, it might be an output to stdout, on others it might be a message box providing options to abort execution or break into the debugger. This method will display the Assert message in the platform specific way. It won't test the expression, or check if this is a debug build - that's all up to the higher-level code.

Parameters:

	expression	The expression which failed and caused the Assert to trigger
	message	User-friendly message to display, explaining what the problem is
	file	Filename of the source file where the Assert was triggered
	line	Line number of the source file where the Assert was triggered

Implemented in Platform_NULL_OS, and Platform_Win32_OS.

virtual void Platform_OS::OutputDebugText	(	const char *	formatstr,
			...
	)			[pure virtual]

It is often useful to be able to print various informational messages for debug purposes. The way this is done will be different for different platforms, so this method abstracts that functionality. OutputDebugText works just like printf, where you supply a format string, indicating where values are to be inserted using d, f etc, followed by all the values to replace those markers.

Implemented in Platform_NULL_OS, and Platform_Win32_OS.

virtual void Platform_OS::ReportFatalError	(	const char *	message,
		const char *	file,
		int	line
	)			[pure virtual]

When something goes so wrong that it is impossible to continue with the execution, this method should be called. It will display the message, in whatever way makes sense for the platform, and then terminate the application. This should be reserved for really severe errors, which can't be handled by the application code.

Parameters:

	message	User-friendly message to display, explaining what the problem is
	file	Filename of the source file where the error occurred
	line	Line number of the source file where the error occurred

Implemented in Platform_NULL_OS, and Platform_Win32_OS.

virtual bool Platform_OS::ExitRequested

(

)

[pure virtual]

Shutdown of the application is controlled by the application main-loop. But on some platforms, a request to terminate can be issued on OS-level, like when you click the Close-button on a window. When that happens, this method will return true from that point onwards, but before that, it will return false. If the application wants to handle OS-level shutdown request, it needs to check this method regularly. On some platforms, this method might never return true.

Returns:

True if the OS are requesting that the application is to be terminated, otherwise false

Implemented in Platform_NULL_OS, and Platform_Win32_OS.