Dali 3D User Interface Engine
List of all members | Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes
Dali::Integration::Core Class Reference

Integration::Core is used for integration with the native windowing system. More...

#include <core.h>

Collaboration diagram for Dali::Integration::Core:
Collaboration graph
[legend]

Public Member Functions

 ~Core ()
 Non-virtual destructor. More...
 
ContextNotifierInterfaceGetContextNotifier ()
 Get the object that will notify the application/toolkit when context is lost/regained. More...
 
void ContextCreated ()
 Notify the Core that the GL context has been created. More...
 
void ContextDestroyed ()
 Notify the Core that that GL context is about to be destroyed. More...
 
void RecoverFromContextLoss ()
 Notify the Core that the GL context has been re-created, e.g. More...
 
void SurfaceResized (unsigned int width, unsigned int height)
 Notify the Core that the GL surface has been resized. More...
 
void SetDpi (unsigned int dpiHorizontal, unsigned int dpiVertical)
 Notify the Core about the display's DPI values. More...
 
void Suspend ()
 Put Core into the suspended state. More...
 
void Resume ()
 Resume the Core from the suspended state. More...
 
void SceneCreated ()
 Notify Core that the scene has been created. More...
 
void QueueEvent (const Event &event)
 Queue an event with Core. More...
 
void ProcessEvents ()
 Process the events queued with QueueEvent(). More...
 
void UpdateTouchData (const TouchData &touch)
 Update external raw touch data in core. More...
 
unsigned int GetMaximumUpdateCount () const
 The Core::Update() method prepares a frame for rendering. More...
 
void Update (float elapsedSeconds, unsigned int lastVSyncTimeMilliseconds, unsigned int nextVSyncTimeMilliseconds, UpdateStatus &status)
 Update the scene for the next frame. More...
 
void Render (RenderStatus &status)
 Render the next frame. More...
 
SystemOverlayGetSystemOverlay ()
 Use the SystemOverlay to draw content for system-level indicators, dialogs etc. More...
 
void SetViewMode (ViewMode viewMode)
 Set the stereoscopic 3D view mode. More...
 
ViewMode GetViewMode () const
 Get the current view mode. More...
 
void SetStereoBase (float stereoBase)
 Set the stereo base (eye seperation) for stereoscopic 3D. More...
 
float GetStereoBase () const
 Get the stereo base (eye seperation) for stereoscopic 3D. More...
 

Static Public Member Functions

static CoreNew (RenderController &renderController, PlatformAbstraction &platformAbstraction, GlAbstraction &glAbstraction, GlSyncAbstraction &glSyncAbstraction, GestureManager &gestureManager, ResourcePolicy::DataRetention policy)
 Create a new Core. More...
 

Private Member Functions

 Core ()
 Private constructor; see also Core::New() More...
 
 Core (const Core &core)
 Undefined copy-constructor. More...
 
Coreoperator= (const Core &rhs)
 Undefined assignment operator. More...
 

Private Attributes

Internal::CoremImpl
 

Detailed Description

Integration::Core is used for integration with the native windowing system.

The following integration tasks must be completed:

1) Handle GL context creation, and notify the Core when this occurs.

2) Provide suspend/resume behaviour (see below for more details).

3) Run an event loop, for passing events to the Core e.g. multi-touch input events. Notification events should be sent after a frame is updated (see UpdateStatus).

4) Run a rendering loop, instructing the Core to render each frame. A separate rendering thread is recommended; see multi-threading options below.

5) Provide an implementation of the PlatformAbstraction interface, used to access platform specific services.

6) Provide an implementation of the GlAbstraction interface, used to access OpenGL services.

7) Provide an implementation of the GestureManager interface, used to register gestures provided by the platform.

Suspend/Resume behaviour:

The Core has no knowledge of the application lifecycle, but can be suspended. In the suspended state, input events will not be processed, and animations will not progress any further. The Core can still render in the suspended state; the same frame will be produced each time.

Multi-threading notes:

The Dali API methods are not reentrant. If you access the API from multiple threads simultaneously, then the results are undefined. This means that your application might segfault, or behave unpredictably.

Rendering strategies:

1) Single-threaded. Call every Core method from the same thread. Event handling and rendering will occur in the same thread. This is not recommended, since processing input (slowly) can affect the smooth flow of animations.

2) Multi-threaded. The Core update & render operations can be processed in separate threads. See the method descriptions in Core to see which thread they should be called from. This is the recommended option, so that input processing will not affect the smoothness of animations. Note that the rendering thread must be halted, before destroying the GL context.

Definition at line 198 of file core.h.

Constructor & Destructor Documentation

Dali::Internal::Core::~Core ( )

Non-virtual destructor.

Core is not intended as a base class.

TODO this should be done by Adaptor, Core does not know about threading First stop the resource loading thread(s)

Definition at line 42 of file core.cpp.

References mImpl.

Dali::Integration::Core::Core ( )
private

Private constructor; see also Core::New()

Definition at line 147 of file core.cpp.

Referenced by New().

Here is the caller graph for this function:

Dali::Integration::Core::Core ( const Core core)
private

Undefined copy-constructor.

This avoids accidental calls to a default copy-constructor.

Parameters
[in]coreA reference to the object to copy.

Member Function Documentation

void Dali::Internal::Core::ContextCreated ( )

Notify the Core that the GL context has been created.

The context must be created before the Core can render. Multi-threading note: this method should be called from the rendering thread only

Postcondition
The Core is aware of the GL context.

Definition at line 52 of file core.cpp.

References ContextCreated(), and mImpl.

Referenced by ContextCreated(), Dali::TestApplication::Initialize(), Dali::TestApplication::ResetContext(), Dali::Internal::Adaptor::RenderThread::Run(), Dali::Internal::Adaptor::SingleThreadController::Start(), Dali::Internal::Adaptor::CombinedUpdateRenderController::UpdateRenderThread(), and UtcDaliShaderBinaries().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::ContextDestroyed ( )

Notify the Core that that GL context is about to be destroyed.

The Core will free any previously allocated GL resources. Multi-threading note: this method should be called from the rendering thread only

Postcondition
The Core is unaware of any GL context.

Definition at line 57 of file core.cpp.

References ContextDestroyed(), and mImpl.

Referenced by ContextDestroyed(), Dali::TestApplication::ResetContext(), Dali::Internal::Adaptor::RenderThread::Run(), Dali::Internal::Adaptor::SingleThreadController::StopRendering(), Dali::Internal::Adaptor::CombinedUpdateRenderController::UpdateRenderThread(), and UtcDaliShaderBinaries().

Here is the call graph for this function:

Here is the caller graph for this function:

Integration::ContextNotifierInterface * Dali::Internal::Core::GetContextNotifier ( )

Get the object that will notify the application/toolkit when context is lost/regained.

Definition at line 47 of file core.cpp.

References GetContextNotifier(), and mImpl.

Referenced by Dali::Internal::Adaptor::Adaptor::ContextLost(), Dali::Internal::Adaptor::Adaptor::ContextRegained(), GetContextNotifier(), UtcDaliStageContextLostSignalP(), and UtcDaliStageContextRegainedSignalP().

Here is the call graph for this function:

Here is the caller graph for this function:

unsigned int Dali::Internal::Core::GetMaximumUpdateCount ( ) const

The Core::Update() method prepares a frame for rendering.

This method determines how many frames may be prepared, ahead of the rendering. For example if the maximum update count is 2, then Core::Update() for frame N+1 may be processed whilst frame N is being rendered. However the Core::Update() for frame N+2 may not be called, until the Core::Render() method for frame N has returned.

Returns
The maximum update count (>= 1).

Definition at line 107 of file core.cpp.

References GetMaximumUpdateCount(), and mImpl.

Referenced by GetMaximumUpdateCount().

Here is the call graph for this function:

Here is the caller graph for this function:

float Dali::Internal::Core::GetStereoBase ( ) const

Get the stereo base (eye seperation) for stereoscopic 3D.

Returns
The stereo base (eye seperation) for stereoscopic 3D (mm)

Definition at line 142 of file core.cpp.

References GetStereoBase(), and mImpl.

Referenced by GetStereoBase(), and Dali::Internal::Adaptor::Adaptor::GetStereoBase().

Here is the call graph for this function:

Here is the caller graph for this function:

Integration::SystemOverlay & Dali::Internal::Core::GetSystemOverlay ( )
ViewMode Dali::Internal::Core::GetViewMode ( ) const

Get the current view mode.

Returns
The current view mode
See Also
SetViewMode.

Definition at line 132 of file core.cpp.

References GetViewMode(), and mImpl.

Referenced by GetViewMode(), and Dali::Internal::Adaptor::Adaptor::GetViewMode().

Here is the call graph for this function:

Here is the caller graph for this function:

Core * Dali::Integration::Core::New ( RenderController renderController,
PlatformAbstraction platformAbstraction,
GlAbstraction glAbstraction,
GlSyncAbstraction glSyncAbstraction,
GestureManager gestureManager,
ResourcePolicy::DataRetention  policy 
)
static

Create a new Core.

This object is used for integration with the native windowing system.

Parameters
[in]renderControllerThe interface to an object which controls rendering.
[in]platformAbstractionThe interface providing platform specific services.
[in]glAbstractionThe interface providing OpenGL services.
[in]glSyncAbstractionThe interface providing OpenGL sync objects.
[in]gestureManagerThe interface providing gesture manager services.
[in]policyThe data retention policy. This depends on application setting and platform support. Dali should honour this policy when deciding to discard intermediate resource data.
Returns
A newly allocated Core.

Definition at line 33 of file core.cpp.

References Core(), and mImpl.

Referenced by Dali::TestApplication::Initialize(), and Dali::Internal::Adaptor::Adaptor::Initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

Core& Dali::Integration::Core::operator= ( const Core rhs)
private

Undefined assignment operator.

This avoids accidental calls to a default assignment operator.

Parameters
[in]rhsA reference to the object to copy.
void Dali::Internal::Core::ProcessEvents ( )

Process the events queued with QueueEvent().

Multi-threading note: this method should be called from the main thread.

Precondition
ProcessEvents should not be called during ProcessEvents.

Definition at line 97 of file core.cpp.

References mImpl, and ProcessEvents().

Referenced by Dali::Internal::Adaptor::Adaptor::ProcessCoreEvents(), Dali::TestApplication::ProcessEvent(), ProcessEvents(), and Dali::TestApplication::SendNotification().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Integration::Core::QueueEvent ( const Event &  event)

Queue an event with Core.

Pre-processing of events may be beneficial e.g. a series of motion events could be throttled, so that only the last event is queued. Multi-threading note: this method should be called from the main thread.

Parameters
[in]eventThe new event.

Definition at line 92 of file core.cpp.

References mImpl, and QueueEvent().

Referenced by Dali::TestApplication::ProcessEvent(), Dali::Internal::Adaptor::Adaptor::QueueCoreEvent(), and QueueEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::RecoverFromContextLoss ( )

Notify the Core that the GL context has been re-created, e.g.

after ReplaceSurface or Context loss.

In the case of ReplaceSurface, both ContextToBeDestroyed() and ContextCreated() will have been called on the render thread before this is called on the event thread.

Multi-threading note: this method should be called from the main thread

Definition at line 62 of file core.cpp.

References mImpl, and RecoverFromContextLoss().

Referenced by Dali::Internal::Adaptor::Adaptor::ContextRegained(), RecoverFromContextLoss(), UtcDaliImageContextLoss(), and UtcDaliNativeImageContextLoss().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::Render ( RenderStatus status)

Render the next frame.

This method should be preceded by a call up Update. Multi-threading note: this method should be called from a dedicated rendering thread.

Precondition
The GL context must have been created, and made current.
Parameters
[out]statusshowing whether update is required to run.

Definition at line 117 of file core.cpp.

References mImpl, and Render().

Referenced by Dali::TestApplication::Render(), Render(), Dali::TestApplication::RenderOnly(), Dali::Internal::Adaptor::SingleThreadController::RequestUpdateOnce(), Dali::Internal::Adaptor::RenderThread::Run(), Dali::Internal::Adaptor::SingleThreadController::UpdateRender(), and Dali::Internal::Adaptor::CombinedUpdateRenderController::UpdateRenderThread().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::Resume ( )

Resume the Core from the suspended state.

At the first update, the elapsed time passed to the animations will be equal to the time spent suspended. Multi-threading note: this method should be called from the main thread

Postcondition
The Core is not in the suspended state.

Definition at line 82 of file core.cpp.

References mImpl, and Resume().

Referenced by Dali::Internal::Adaptor::Adaptor::Resume(), and Resume().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::SceneCreated ( )

Notify Core that the scene has been created.

Definition at line 87 of file core.cpp.

References mImpl, and SceneCreated().

Referenced by Dali::TestApplication::Initialize(), Dali::Internal::Adaptor::Adaptor::NotifySceneCreated(), Dali::Internal::Adaptor::Adaptor::SceneCreated(), SceneCreated(), and UtcDaliStageSceneCreatedSignalP().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::SetDpi ( unsigned int  dpiHorizontal,
unsigned int  dpiVertical 
)

Notify the Core about the display's DPI values.

This should be done after the display is initialized and a Core instance is created. The Core will use the DPI values for font rendering. Multi-threading note: this method should be called from the main thread

Parameters
[in]dpiHorizontalHorizontal DPI value.
[in]dpiVerticalVertical DPI value.

Definition at line 72 of file core.cpp.

References mImpl, and SetDpi().

Referenced by Dali::TestApplication::Initialize(), SetDpi(), Dali::Internal::Adaptor::Adaptor::Start(), and UtcDaliStageGetDpiP2().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::SetStereoBase ( float  stereoBase)

Set the stereo base (eye seperation) for stereoscopic 3D.

Parameters
[in]stereoBaseThe stereo base (eye seperation) for stereoscopic 3D (mm)

Definition at line 137 of file core.cpp.

References mImpl, and SetStereoBase().

Referenced by SetStereoBase(), and Dali::Internal::Adaptor::Adaptor::SetStereoBase().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::SetViewMode ( ViewMode  viewMode)

Set the stereoscopic 3D view mode.

Parameters
[in]viewModeThe new view mode

Definition at line 127 of file core.cpp.

References mImpl, and SetViewMode().

Referenced by SetViewMode(), and Dali::Internal::Adaptor::Adaptor::SetViewMode().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::SurfaceResized ( unsigned int  width,
unsigned int  height 
)

Notify the Core that the GL surface has been resized.

This should be done at least once i.e. after the first call to ContextCreated(). The Core will use the surface size for camera calculations, and to set the GL viewport. Multi-threading note: this method should be called from the main thread

Parameters
[in]widthThe new surface width.
[in]heightThe new surface height.

Definition at line 67 of file core.cpp.

References mImpl, and SurfaceResized().

Referenced by Dali::TestApplication::Initialize(), Dali::TestApplication::SetSurfaceWidth(), Dali::Internal::Adaptor::Adaptor::Start(), SurfaceResized(), and Dali::Internal::Adaptor::Adaptor::SurfaceSizeChanged().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::Suspend ( )

Put Core into the suspended state.

Any ongoing event processing will be cancelled, for example multi-touch sequences. The core expects the system has suspended us. Animation time will continue during the suspended state. Multi-threading note: this method should be called from the main thread

Postcondition
The Core is in the suspended state.

Definition at line 77 of file core.cpp.

References mImpl, and Suspend().

Referenced by Dali::Internal::Adaptor::Adaptor::Pause(), Dali::Internal::Adaptor::Adaptor::Stop(), and Suspend().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::Update ( float  elapsedSeconds,
unsigned int  lastVSyncTimeMilliseconds,
unsigned int  nextVSyncTimeMilliseconds,
Integration::UpdateStatus status 
)

Update the scene for the next frame.

This method must be called before each frame is rendered. Multi-threading notes: this method should be called from a dedicated update-thread. The update for frame N+1 may be processed whilst frame N is being rendered. However the update-thread must wait until frame N has been rendered, before processing frame N+2. After this method returns, messages may be queued internally for the main thread. In order to process these messages, a notification is sent via the main thread's event loop.

Parameters
[in]elapsedSecondsNumber of seconds since the last call
[in]lastVSyncTimeMillisecondsThe last vsync time in milliseconds
[in]nextVSyncTimeMillisecondsThe time of the next predicted VSync in milliseconds
[out]statusshowing whether further updates are required. This also shows whether a Notification event should be sent, regardless of whether the multi-threading is used.

Definition at line 112 of file core.cpp.

References mImpl, and Update().

Referenced by Dali::TestApplication::DoUpdate(), Dali::Internal::Adaptor::SingleThreadController::RequestUpdateOnce(), Dali::Internal::Adaptor::UpdateThread::Run(), Update(), Dali::Internal::Adaptor::SingleThreadController::UpdateRender(), and Dali::Internal::Adaptor::CombinedUpdateRenderController::UpdateRenderThread().

Here is the call graph for this function:

Here is the caller graph for this function:

void Dali::Internal::Core::UpdateTouchData ( const TouchData touch)

Update external raw touch data in core.

The core will use the touch data to generate Dali Touch/Gesture events for applications to use in the update thread.

Parameters
[in]touchThe raw touch data.
Note
This can be called from either the event thread OR a dedicated touch thread.

Definition at line 102 of file core.cpp.

References mImpl, and UpdateTouchData().

Referenced by UpdateTouchData().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

Internal::Core* Dali::Integration::Core::mImpl
private

The documentation for this class was generated from the following files:
Dali Docs Home
Read more about Dali