OSDL::CommonModule Class Reference

#include <OSDLBasic.h>

Collaboration diagram for OSDL::CommonModule:

[legend]

List of all members.

Detailed Description

Root of all OSDL modules.

From this common module, all other modules can be triggered.

Definition at line 95 of file OSDLBasic.h.


Public Types
typedef Ceylan::Sint32	BackendReturnCode
	Data type of back-end return code:.
Public Member Functions
virtual bool	hasVideoModule () const throw ()
	Tells whether a video module is available.
virtual Video::VideoModule &	getVideoModule () const throw ( OSDL::Exception )
	Returns current video module.
virtual bool	hasEventsModule () const throw ()
	Tells whether a video module is available.
virtual Events::EventsModule &	getEventsModule () const throw ( OSDL::Exception )
	Returns current events module.
virtual bool	hasAudioModule () const throw ()
	Tells whether a video module is available.
virtual Audio::AudioModule &	getAudioModule () const throw ( OSDL::Exception )
	Returns current audio module.
virtual Ceylan::Flags	getFlags () const throw ()
	Returns flags used for this common module.
virtual bool	hasCDROMDriveHandler () const throw ()
	Tells whether a CD-ROM drive handler is available.
virtual CDROMDriveHandler &	getCDROMDriveHandler () const throw ( OSDL::Exception )
	Returns current CD-ROM handler.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const throw ()
	Returns an user-friendly description of the state of this object.
Static Public Member Functions
static std::string	InterpretFlags (Ceylan::Flags flags) throw ()
	Describes specified top-level flags used to initialize the SDL back-end.
static std::string	DescribeEnvironmentVariables () throw ()
	Returns a summary about the possible use of general-purpose* environment variables, for the selected back-end, expressed in specified format.
static bool	IsBackendInitialized () throw ()
Static Public Attributes
static const BackendReturnCode	BackendSuccess = 0
	Exported logical value for back-end success.
static const BackendReturnCode	BackendError = -1
	Exported logical value for back-end success/.
static const Ceylan::Flags	UseTimer = 0x00000001
	Initializes the timer subsystem.
static const Ceylan::Flags	UseAudio = 0x00000010
	Initializes the audio subsystem.
static const Ceylan::Flags	UseVideo = 0x00000020
	Initializes the video subsystem.
static const Ceylan::Flags	UseCDROM = 0x00000100
	Initializes the CD-ROM subsystem.
static const Ceylan::Flags	UseJoystick = 0x00000200
	Initializes the joystick subsystem, implies initializing the video (UseVideo).
static const Ceylan::Flags	UseKeyboard = 0x4000
	Initializes the keyboard subsystem, implies initializing the video (UseVideo).
static const Ceylan::Flags	UseMouse = 0x8000
	Initializes the mouse subsystem, implies initializing the video (UseVideo).
static const Ceylan::Flags	UseEvents
	Initializes the events subsystem, implies initializing the video (UseVideo).
static const Ceylan::Flags	UseEverything = 0x0000FFFF
	Initializes all above subsystems.
static const Ceylan::Flags	NoParachute = 0x00100000
	Do not catch fatal signals.
static const Ceylan::Flags	UseEventThread = 0x01000000
	Initializes the event thread.
Static Protected Member Functions
static Ceylan::Flags	AutoCorrectFlags (Ceylan::Flags inputFlags) throw ()
	Corrects the input flags, formatted as parameters used to create the common module, so that they can be retain directly, without further change.
Protected Attributes
Video::VideoModule *	_video
	Pointer to the current video module used, if any.
Events::EventsModule *	_events
	Pointer to the current events module used, if any.
Audio::AudioModule *	_audio
	Pointer to the current video module used, if any.
Ceylan::Flags	_flags
	Flags used for this common module.
CDROMDriveHandler *	_cdromHandler
	Pointer to the current CD-ROM drive handler used, if any.
Static Protected Attributes
static bool	_BackendInitialized = false
	Tells whether the back-end used by OSDL is initialized.
static CommonModule *	_CurrentCommonModule = 0
	The common module being currently used, if any.
static const std::string	_SDLEnvironmentVariables [] = {}
	Array of all known general purpose environment variables, for SDL back-end.
Private Member Functions
	CommonModule (Ceylan::Flags flags) throw ( OSDL::Exception )
	Initializes OSDL system common module.
virtual	~CommonModule () throw ()
	Stops OSDL system common module.
Friends
OSDL_DLL friend CommonModule &	getCommonModule (Ceylan::Flags flags) throw ()
	This friend function is intended to be the initial means of getting a reference to the common module: this is the entry point to the whole OSDL system.
OSDL_DLL friend bool	hasExistingCommonModule () throw ()
	Tells whether there already exists a common module.
OSDL_DLL friend CommonModule &	getExistingCommonModule () throw ()
	This friend function is intended to be the usual means of getting a reference to the common module, which must already exist.
OSDL_DLL friend void	stop () throw ()
	This friend function allows to shutdown all OSDL services.

Member Typedef Documentation

typedef Ceylan::Sint32 OSDL::CommonModule::BackendReturnCode

Data type of back-end return code:.

Definition at line 160 of file OSDLBasic.h.

Constructor & Destructor Documentation

OSDL::CommonModule::CommonModule ( Ceylan::Flags flags ) throw ( OSDL::Exception ) [explicit, private]

Initializes OSDL system common module.

Parameters:

flags

parameters to initialize SDL.

Note:: To have the common module created, use getCommonModule.

Referenced by OSDL::getCommonModule().

CommonModule::~CommonModule ( ) throw () [private, virtual]

Stops OSDL system common module.

See also:: SDL_Quit defined in http://sdldoc.csn.ul.ie/sdlquit.php.

Definition at line 372 of file OSDLBasic.cc.

References _audio, _cdromHandler, _events, and _video.

Member Function Documentation

bool CommonModule::hasVideoModule ( ) const throw () [virtual]

Tells whether a video module is available.

Definition at line 485 of file OSDLBasic.cc.

References _video.

Referenced by OSDL::Video::VideoModule::GetAntiAliasingState(), OSDL::Video::VideoModule::GetEndPointDrawState(), OSDL::Video::VideoModule::IsDisplayInitialized(), and OSDL::Video::Overlay::Overlay().

Video::VideoModule & CommonModule::getVideoModule ( ) const throw ( OSDL::Exception ) [virtual]

Returns current video module.

Exceptions:

OSDL::Exception

is not video module is available.

Definition at line 494 of file OSDLBasic.cc.

References _video.

Referenced by OSDL::Events::EventsModule::enterBasicMainLoop(), OSDL::Video::VideoModule::GetAntiAliasingState(), OSDL::Video::VideoModule::GetEndPointDrawState(), OSDL::Video::VideoModule::IsDisplayInitialized(), OSDL::Events::EventsModule::onResizedWindow(), OSDL::Events::EventsModule::onScreenNeedsRedraw(), OSDL::Video::Overlay::Overlay(), and OSDL::Engine::Scheduler::schedule().

bool CommonModule::hasEventsModule ( ) const throw () [virtual]

Tells whether a video module is available.

Definition at line 508 of file OSDLBasic.cc.

References _events.

Events::EventsModule & CommonModule::getEventsModule ( ) const throw ( OSDL::Exception ) [virtual]

Returns current events module.

Exceptions:

OSDL::Exception

is not events module is available.

Definition at line 517 of file OSDLBasic.cc.

References _events.

Referenced by OSDL::Engine::Scheduler::schedule().

bool CommonModule::hasAudioModule ( ) const throw () [virtual]

Tells whether a video module is available.

Definition at line 531 of file OSDLBasic.cc.

References _audio.

Audio::AudioModule & CommonModule::getAudioModule ( ) const throw ( OSDL::Exception ) [virtual]

Returns current audio module.

Exceptions:

OSDL::Exception

is not audio module is available.

Definition at line 540 of file OSDLBasic.cc.

References _audio.

Referenced by OSDL::Audio::getExistingAudioModule().

Flags CommonModule::getFlags ( ) const throw () [virtual]

Returns flags used for this common module.

Definition at line 554 of file OSDLBasic.cc.

References _flags.

Referenced by OSDL::getCommonModule().

bool CommonModule::hasCDROMDriveHandler ( ) const throw () [virtual]

Tells whether a CD-ROM drive handler is available.

Definition at line 563 of file OSDLBasic.cc.

References _cdromHandler.

CDROMDriveHandler & CommonModule::getCDROMDriveHandler ( ) const throw ( OSDL::Exception ) [virtual]

Returns current CD-ROM handler.

Exceptions:

OSDL::Exception

is not CD-ROM handler is available.

Definition at line 571 of file OSDLBasic.cc.

References _cdromHandler.

const string CommonModule::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const throw () [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Definition at line 585 of file OSDLBasic.cc.

References _audio, _cdromHandler, _events, _flags, _video, OSDL::GetVersion(), InterpretFlags(), and OSDL::Video::Pixels::toString().

static std::string OSDL::CommonModule::InterpretFlags ( Ceylan::Flags flags ) throw () [static]

Describes specified top-level flags used to initialize the SDL back-end.

Parameters:

flags

Note:: One shall not call this method on flags used with setMode or for a surface. Use VideoModule::interpretFlags or Surface::interpretFlags instead, since their meaning is different.

Referenced by toString().

string CommonModule::DescribeEnvironmentVariables ( ) throw () [static]

Returns a summary about the possible use of general-purpose* environment variables, for the selected back-end, expressed in specified format.

Note:: The SDL back-end can be partly driven by a set of environment variables.

Definition at line 648 of file OSDLBasic.cc.

References _SDLEnvironmentVariables, and OSDL::Video::Pixels::toString().

bool CommonModule::IsBackendInitialized ( ) throw () [static]

Definition at line 709 of file OSDLBasic.cc.

References _BackendInitialized.

Referenced by OSDL::Events::EventsModule::enterMainLoop(), and OSDL::Events::EventsModule::GetMillisecondsSinceStartup().

static Ceylan::Flags OSDL::CommonModule::AutoCorrectFlags ( Ceylan::Flags inputFlags ) throw () [static, protected]

Corrects the input flags, formatted as parameters used to create the common module, so that they can be retain directly, without further change.

For example, if an event source such as a joystick is selected, then the video module must be activated, even if not explicitly selected, otherwise no event at all will be available. Thus the method will fix the flags so that they are consistent.

Referenced by OSDL::getCommonModule().

Friends And Related Function Documentation

OSDL_DLL friend CommonModule& getCommonModule ( Ceylan::Flags flags ) throw () [friend]

This friend function is intended to be the initial means of getting a reference to the common module: this is the entry point to the whole OSDL system.

Parameters:

flags

The requested flags for this common root module, any OR'd combination of CommonModule static flags, so that associated subsystems are instanciated.

See also:: UseTimer, UseAudio, UseVideo, UseCDROM, UseJoystick, UseEverything, NoParachute, UseEventThread, etc.

Note:: UseVideo is required to start the event loop, so it is implied by the UseJoystick flag.
This method is not static to avoid pitfalls of static initializer ordering.

OSDL_DLL friend bool hasExistingCommonModule ( ) throw () [friend]

Tells whether there already exists a common module.

Definition at line 833 of file OSDLBasic.cc.

OSDL_DLL friend CommonModule& getExistingCommonModule ( ) throw () [friend]

This friend function is intended to be the usual means of getting a reference to the common module, which must already exist.

If not, a fatal error will be triggered (not an exception to avoid handling it in all user methods).

Note:: This function is mainly useful for the OSDL internals, if sub-modules, such as the event module, needed access to the common module.

See also:: hasCommonModule()

Note:: This method is not static to avoid pitfalls of static initializer ordering.

Definition at line 842 of file OSDLBasic.cc.

OSDL_DLL friend void stop ( ) throw () [friend]

This friend function allows to shutdown all OSDL services.

Definition at line 855 of file OSDLBasic.cc.

Member Data Documentation

const CommonModule::BackendReturnCode CommonModule::BackendSuccess = 0 [static]

Exported logical value for back-end success.

Definition at line 164 of file OSDLBasic.h.

Referenced by OSDL::Audio::AudioModule::AudioModule(), OSDL::CDROMDriveHandler::CDROMDriveHandler(), and OSDL::Video::VideoModule::VideoModule().

const CommonModule::BackendReturnCode CommonModule::BackendError = -1 [static]

Exported logical value for back-end success/.

Prefer only testing against SDLSuccess: if ( [...] != BackendSuccess ) ...

Definition at line 174 of file OSDLBasic.h.

const Ceylan::Flags CommonModule::UseTimer = 0x00000001 [static]

Initializes the timer subsystem.

Definition at line 307 of file OSDLBasic.h.

const Ceylan::Flags CommonModule::UseAudio = 0x00000010 [static]

Initializes the audio subsystem.

Definition at line 310 of file OSDLBasic.h.

Referenced by OSDL::Audio::AudioModule::AudioModule(), and OSDL::Audio::AudioModule::~AudioModule().

const Ceylan::Flags CommonModule::UseVideo = 0x00000020 [static]

Initializes the video subsystem.

Definition at line 313 of file OSDLBasic.h.

Referenced by OSDL::Video::VideoModule::VideoModule(), and OSDL::Video::VideoModule::~VideoModule().

const Ceylan::Flags CommonModule::UseCDROM = 0x00000100 [static]

Initializes the CD-ROM subsystem.

Definition at line 316 of file OSDLBasic.h.

Referenced by OSDL::CDROMDriveHandler::CDROMDriveHandler(), and OSDL::CDROMDriveHandler::~CDROMDriveHandler().

const Ceylan::Flags CommonModule::UseJoystick = 0x00000200 [static]

Initializes the joystick subsystem, implies initializing the video (UseVideo).

Definition at line 324 of file OSDLBasic.h.

Referenced by OSDL::Events::JoystickHandler::~JoystickHandler().

const Ceylan::Flags CommonModule::UseKeyboard = 0x4000 [static]

Initializes the keyboard subsystem, implies initializing the video (UseVideo).

Definition at line 332 of file OSDLBasic.h.

const Ceylan::Flags CommonModule::UseMouse = 0x8000 [static]

Initializes the mouse subsystem, implies initializing the video (UseVideo).

Definition at line 340 of file OSDLBasic.h.

const Ceylan::Flags CommonModule::UseEvents [static]

Initial value:

    UseJoystick | UseKeyboard | UseMouse

Initializes the events subsystem, implies initializing the video (UseVideo).

This is just a convenience flag gathering all event-related flags (UseJoystick, UseKeyboard, UseMouse, etc.)

Definition at line 351 of file OSDLBasic.h.

const Ceylan::Flags CommonModule::UseEverything = 0x0000FFFF [static]

Initializes all above subsystems.

Definition at line 355 of file OSDLBasic.h.

const Ceylan::Flags CommonModule::NoParachute = 0x00100000 [static]

Do not catch fatal signals.

By default fatal signals are caught, so that if your program crashes, the resulting exception will be intercepted in order to clean up and return the display to a usable state.

However this system does not behave nicely with debuggers, so it might be disabled (mostly for debugging purpose) with this flag.

Note:: If this flag is used, fatal signals will not be caught which may, on some platforms, force the user to reboot. For instance, if a X11 fullscreen application crashes or exits without quitting properly, using the 'NoParachute' flag leaves the desktop to the fullscreen application resolution, that is often far lower than the original desktop resolution, which annoys the user.

Definition at line 378 of file OSDLBasic.h.

const Ceylan::Flags CommonModule::UseEventThread = 0x01000000 [static]

Initializes the event thread.

Definition at line 382 of file OSDLBasic.h.

Video::VideoModule* OSDL::CommonModule::_video [protected]

Pointer to the current video module used, if any.

Definition at line 407 of file OSDLBasic.h.

Referenced by getVideoModule(), hasVideoModule(), toString(), and ~CommonModule().