You.i Engine
CYIApp Class Referenceabstract

Detailed Description

The base class for all applications.

Typically, applications derive from the CYIApp base class and implement key methods. These methods are then called by the platform, which controls the lifecycle, timing and input for applications.

CYIApp::Init() is the entry point for the initialization process, this will trigger calls to UserInit() and UserStart() in which users can specify custom initialization steps.

CYIApp::UserUpdate() will be triggered on each application tick

#include <framework/YiApp.h>

Public Types

enum  MemoryLevel {
  MemoryLevel::Moderate,
  MemoryLevel::Low,
  MemoryLevel::Critical
}
 

Public Member Functions

 CYIApp ()
 
virtual ~CYIApp ()
 
bool Init ()
 
bool Init (std::unique_ptr< CYIFocusEngine > pFocusEngine)
 
bool IsInitialized () const
 
void SetDefaultOrientation (CYIScreenProperty::Orientation orientation)
 
CYIScreenProperty::Orientation GetDefaultOrientation () const
 
void SetDefaultStatusBarVisibility (CYIScreenProperty::StatusBar statusbar)
 
CYIScreenProperty::StatusBar GetDefaultStatusBarVisibility () const
 
void SetDefaultNavigationBarVisibility (CYIScreenProperty::NavigationBar navigationBar)
 
CYIScreenProperty::NavigationBar GetDefaultNavigationBarVisibility () const
 
bool SetScreenProperties (int screenSizeX, int screenSizeY, int screenDensityX, int screenDensityY)
 
bool SetScreen (const CYIScreen &screen)
 
bool SetSurface (CYISurface *pSurface)
 
void SurfaceWasResized (int32_t width, int32_t height)
 
virtual CYIFrameworkConfiguration UserConfiguration ()
 
virtual void HandleKeyInputs (const CYIKeyEvent &keyEvent)
 
virtual void HandleActionInputs (int32_t x, int32_t y, CYIEvent::Type eventType, uint8_t pointerID=0, bool hover=false)
 
virtual void HandleActionInputs (int32_t x, int32_t y, int32_t wheelDelta, CYIActionEvent::ButtonType button, CYIEvent::Type eventType, uint8_t pointerID=0, bool hover=false)
 
void HandleTapGestureInputs (int32_t x, int32_t y, uint32_t numberOfFingers, CYIEvent::Type eventType)
 
void HandleSwipeGestureInputs (uint32_t numberOfFingers, CYISwipeGestureEvent::Direction direction, CYIEvent::Type eventType)
 
void HandleDragGestureInputs (int32_t x, int32_t y, uint32_t numberOfFingers, CYIGestureEvent::State state, CYIEvent::Type eventType)
 
void HandleScrubGestureInputs (uint32_t numberOfFingers, CYIEvent::Type eventType)
 
virtual void HandleLowMemory (MemoryLevel memoryLevel)
 
bool LoadFont (const CYIString &URI, ssize_t *pFontID, bool local=false)
 
bool LoadFont (const uint8_t *pFontData, uint32_t dataSize, ssize_t *pFontID)
 
CYIFrameworkGetMainFramework ()
 
CYIRenderSystemGetMainRenderSystem ()
 
virtual CYISceneManagerGetSceneManager () const
 
bool PostEvent (std::unique_ptr< CYIEvent > pEvent, CYIEvent::Priority priority=CYIEvent::Priority::Default, bool bump=false)
 
bool PostEvent (std::unique_ptr< CYIEvent > pEvent, CYIEventHandler *pDestination, CYIEvent::Priority priority=CYIEvent::Priority::Default, bool bump=false)
 
bool SendEvent (std::unique_ptr< CYIEvent > pEvent)
 
bool SendEvent (std::unique_ptr< CYIEvent > pEvent, CYIEventHandler *pDestination)
 
bool Update (bool forceDirty=false, bool updateTime=true)
 
virtual void Draw ()
 
virtual void OnPreDraw ()
 
virtual void OnPostDraw ()
 
virtual void Swap ()
 
void SetHUDVisibility (bool visible)
 
bool IsHUDVisible () const
 
CYIHudGetHUD ()
 
const CYIHudGetHUD () const
 
void SetShowFPS (bool show)
 
bool GetShowFPS () const
 
CYIDevPanelGetDevPanel () const
 
void InitializeDevPanel ()
 
void DestroyDevPanel ()
 
void SetAssetsPath (const CYIString &assetsPath)
 
const CYIStringGetAssetsPath () const
 
void SetCachePath (const CYIString &cachePath)
 
const CYIStringGetCachePath () const
 
void SetDataPath (const CYIString &dataPath)
 
const CYIStringGetDataPath () const
 
void SetExternalPath (const CYIString &externalPath)
 
const CYIStringGetExternalPath () const
 
void SetVersion (const CYIString &version)
 
const CYIStringGetVersion () const
 
void SetMultiTouchEnabled (bool enabled)
 
bool IsMultiTouchEnabled () const
 
void SetBackgroundColor (const CYIColor &color)
 
const CYIColorGetBackgroundColor ()
 
void SetRenderingThrottling (bool bThrottle)
 
bool IsRenderingThrottled () const
 

Public Attributes

CYISignal< int32_t, int32_t > SurfaceSizeChanged
 

Protected Member Functions

 CYIApp (CYIAppPriv *pPriv)
 
virtual bool UserInit ()=0
 
virtual bool UserStart ()=0
 
virtual void UserUpdate ()
 
virtual void OnSurfaceSizeChanged (int32_t width, int32_t height)
 

Protected Attributes

CYIAppPrivm_pPriv
 

Friends

class CYIFPSWidget
 
class CYIAppPriv
 

Member Enumeration Documentation

◆ MemoryLevel

enum CYIApp::MemoryLevel
strong
Enumerator
Moderate 
Low 
Critical 

Constructor & Destructor Documentation

◆ CYIApp() [1/2]

CYIApp::CYIApp ( )

◆ ~CYIApp()

virtual CYIApp::~CYIApp ( )
virtual

◆ CYIApp() [2/2]

CYIApp::CYIApp ( CYIAppPriv pPriv)
protected

Member Function Documentation

◆ DestroyDevPanel()

void CYIApp::DestroyDevPanel ( )

Destroys the dev panel, if one exists.

◆ Draw()

virtual void CYIApp::Draw ( )
virtual

This function draws the results of the previous Update() to the screen. If nothing has been updated, the screen buffer will not be re-drawn.

◆ GetAssetsPath()

const CYIString& CYIApp::GetAssetsPath ( ) const

Retrieve the asset location. This location is generally read-only. See also SetAssetsPath

◆ GetBackgroundColor()

const CYIColor& CYIApp::GetBackgroundColor ( )

Returns the current app background color.

See also
SetBackgroundColor

◆ GetCachePath()

const CYIString& CYIApp::GetCachePath ( ) const

Retrieve the cache location. This location generally persists for the install life of the application, but the data may be cleared between application launches. The data path will be returned if no cache path has been set, or has been set to an empty string. See also SetCachePath and SetDataPath.

◆ GetDataPath()

const CYIString& CYIApp::GetDataPath ( ) const

Retrieve the data location. This location generally persists for the install life of the application. See also SetDataPath

◆ GetDefaultNavigationBarVisibility()

CYIScreenProperty::NavigationBar CYIApp::GetDefaultNavigationBarVisibility ( ) const

◆ GetDefaultOrientation()

CYIScreenProperty::Orientation CYIApp::GetDefaultOrientation ( ) const

◆ GetDefaultStatusBarVisibility()

CYIScreenProperty::StatusBar CYIApp::GetDefaultStatusBarVisibility ( ) const

◆ GetDevPanel()

CYIDevPanel* CYIApp::GetDevPanel ( ) const

Returns the instance of the dev panel. May return null if such an instance doesn't exist.

Note
This function typically returns nullptr for Release builds, unless the InitializeDevPanel function has explicitly been called.

◆ GetExternalPath()

const CYIString& CYIApp::GetExternalPath ( ) const

Get the external storage location. This location generally persists beyond the install life of the application. See also SetExternalPath

Note
The "WRITE_EXTERNAL_STORAGE" permission is required to read or write to this path on Android.

◆ GetHUD() [1/2]

CYIHud& CYIApp::GetHUD ( )

Returns the CYIHud instance used by this app.

◆ GetHUD() [2/2]

const CYIHud& CYIApp::GetHUD ( ) const

Returns the CYIHud instance used by this app.

◆ GetMainFramework()

CYIFramework* CYIApp::GetMainFramework ( )

Returns the main application framework, equivalent to CYIFramework::GetInstance()

◆ GetMainRenderSystem()

CYIRenderSystem* CYIApp::GetMainRenderSystem ( )

Returns the main application render system, equivalent to CYIRenderSystem::GetInstance()

◆ GetSceneManager()

virtual CYISceneManager* CYIApp::GetSceneManager ( ) const
virtual

Returns the scene manager for this application. The scene manager is the entry point for interacting with a 3D scene

◆ GetShowFPS()

bool CYIApp::GetShowFPS ( ) const

Returns true if FPS rendering is enabled, false otherwise

Deprecated:
This function has been deprecated and may be removed in a future release. IsHUDVisible should be used instead.

◆ GetVersion()

const CYIString& CYIApp::GetVersion ( ) const

Returns the application version string for this application object.

◆ HandleActionInputs() [1/2]

virtual void CYIApp::HandleActionInputs ( int32_t  x,
int32_t  y,
CYIEvent::Type  eventType,
uint8_t  pointerID = 0,
bool  hover = false 
)
virtual

Handles action input events, posting them to the event queue to be processed. If the surface is not available, no event will be posted.

Pass in the x and y coordinates of the event along with the event type, the pointer id (if applicable) and the hover flag (if applicable).

Applicable event types are: CYIEvent::Type::ActionDown CYIEvent::Type::ActionMove CYIEvent::Type::ActionUp CYIEvent::Type::ActionWheel CYIEvent::Type::ActionWheelHorizontal CYIEvent::Type::ActionWheelVertical

◆ HandleActionInputs() [2/2]

virtual void CYIApp::HandleActionInputs ( int32_t  x,
int32_t  y,
int32_t  wheelDelta,
CYIActionEvent::ButtonType  button,
CYIEvent::Type  eventType,
uint8_t  pointerID = 0,
bool  hover = false 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ HandleDragGestureInputs()

void CYIApp::HandleDragGestureInputs ( int32_t  x,
int32_t  y,
uint32_t  numberOfFingers,
CYIGestureEvent::State  state,
CYIEvent::Type  eventType 
)

Handles drag gesture input events, posting them to the event queue to be processed. If the surface is not available, no event will be posted.

Because drag gestures are continuous (i.e. they emit multiple events during the life of the gesture), the caller must pass in the gesture state.

Applicable event types are: CYIEvent::Type::GestureDrag

See also
CYIGestureEvent::State

◆ HandleKeyInputs()

virtual void CYIApp::HandleKeyInputs ( const CYIKeyEvent keyEvent)
virtual

Handles key input events, posting them to the event queue to be processed.

◆ HandleLowMemory()

virtual void CYIApp::HandleLowMemory ( MemoryLevel  memoryLevel)
virtual

This may be called by the platform during low-memory conditions.

◆ HandleScrubGestureInputs()

void CYIApp::HandleScrubGestureInputs ( uint32_t  numberOfFingers,
CYIEvent::Type  eventType 
)

Handles scrub gesture input events, posting them to the event queue to be processed. If the surface is not available, no event will be posted.

The recognized scrub gesture pattern is only "Z" (swipe right->left->right), which can be extended in the future.

Applicable event types are: CYIEvent::Type::GestureScrub

◆ HandleSwipeGestureInputs()

void CYIApp::HandleSwipeGestureInputs ( uint32_t  numberOfFingers,
CYISwipeGestureEvent::Direction  direction,
CYIEvent::Type  eventType 
)

Handles swipe gesture input events, posting them to the event queue to be processed. If the surface is not available, no event will be posted.

Applicable event types are: CYIEvent::Type::GestureSwipe

◆ HandleTapGestureInputs()

void CYIApp::HandleTapGestureInputs ( int32_t  x,
int32_t  y,
uint32_t  numberOfFingers,
CYIEvent::Type  eventType 
)

Handles tap gesture input events, posting them to the event queue to be processed. If the surface is not available, no event will be posted.

Applicable event types are: CYIEvent::Type::GestureTap CYIEvent::Type::GestureDoubleTap

◆ Init() [1/2]

bool CYIApp::Init ( )

This function must be called by the user in the Drawing context. This function will initialize the user application along with the You.i Engine framework. This functions has hooks to UserInit() and UserStart() to allow the user insert application specific behaviour.

◆ Init() [2/2]

bool CYIApp::Init ( std::unique_ptr< CYIFocusEngine pFocusEngine)

This function must be called by the user in the Drawing context. This function will initialize the user application along with the You.i Engine framework. This functions has hooks to UserInit() and UserStart() to allow the user insert application specific behaviour.

◆ InitializeDevPanel()

void CYIApp::InitializeDevPanel ( )

Constructs an instance of the dev panel, if one doesn't exist already.

◆ IsHUDVisible()

bool CYIApp::IsHUDVisible ( ) const

Returns true if the HUD is visible, false otherwise.

◆ IsInitialized()

bool CYIApp::IsInitialized ( ) const

Returns true if the application has already been initialized. On some platforms, and application can receive an event prior to You.i Engine being initialized.

◆ IsMultiTouchEnabled()

bool CYIApp::IsMultiTouchEnabled ( ) const

Return true if multi-touch events are being sent to the application.

◆ IsRenderingThrottled()

bool CYIApp::IsRenderingThrottled ( ) const

Returns true if rendering is throttled.

See also
SetRenderingThrottling

◆ LoadFont() [1/2]

bool CYIApp::LoadFont ( const CYIString URI,
ssize_t pFontID,
bool  local = false 
)

Load a font, located at the specified URI into the text engine. The font's id will be stored in pFontID. local indicates whether the path is a local path

◆ LoadFont() [2/2]

bool CYIApp::LoadFont ( const uint8_t *  pFontData,
uint32_t  dataSize,
ssize_t pFontID 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This function loads binary font data into the text engine.

◆ OnPostDraw()

virtual void CYIApp::OnPostDraw ( )
inlinevirtual

Optional method to allow the app to draw things after You.i Engine renders, but before it swaps. This can be used to render debug information on top of everything.

This is called right after Draw()

◆ OnPreDraw()

virtual void CYIApp::OnPreDraw ( )
inlinevirtual

Optional method to allow the app to prepare or render things before You.i Engine renders. This could be useful for example on platforms that need to render a video before everything else.

This is called before CYISceneManager::Draw(). Event processing will be complete prior to this call.

◆ OnSurfaceSizeChanged()

virtual void CYIApp::OnSurfaceSizeChanged ( int32_t  width,
int32_t  height 
)
protectedvirtual

Function will be called when the surface size changes. Subclasses can use this to update their views based on the new size.

Note
Overriding without calling the base implementation will prevent the scene manager from updating for the surface size change. When the scene manager does not update for a surface size change scenes in the scene manager and the scene manager background will not ube updated to be consistent with the new surface size.
See also
CYISceneManager::OnSurfaceSizeChanged
CYISceneManager::UpdateAllScenes
CYISceneManager::UpdateBackground

◆ PostEvent() [1/2]

bool CYIApp::PostEvent ( std::unique_ptr< CYIEvent pEvent,
CYIEvent::Priority  priority = CYIEvent::Priority::Default,
bool  bump = false 
)

Posts an event to the event dispatcher with priority priority. If bump is true, then the event will be pushed to the top of the event queue.

◆ PostEvent() [2/2]

bool CYIApp::PostEvent ( std::unique_ptr< CYIEvent pEvent,
CYIEventHandler pDestination,
CYIEvent::Priority  priority = CYIEvent::Priority::Default,
bool  bump = false 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ SendEvent() [1/2]

bool CYIApp::SendEvent ( std::unique_ptr< CYIEvent pEvent)

Immediately dispatch an event

◆ SendEvent() [2/2]

bool CYIApp::SendEvent ( std::unique_ptr< CYIEvent pEvent,
CYIEventHandler pDestination 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ SetAssetsPath()

void CYIApp::SetAssetsPath ( const CYIString assetsPath)

Specify the location from which application assets will be loaded, this is generally a read-only location and will be treated as such.

◆ SetBackgroundColor()

void CYIApp::SetBackgroundColor ( const CYIColor color)

Sets the background color for the app which will be visible behind the bottom-most scene if it has a transparent background.

The default app background color is CYIColor::Named().Black.

◆ SetCachePath()

void CYIApp::SetCachePath ( const CYIString cachePath)

Specify the location to which the application can cache files, the app needs write permissions to this location. The path should point to a directory that will be destroyed upon uninstallation.

◆ SetDataPath()

void CYIApp::SetDataPath ( const CYIString dataPath)

Specify the location to which the application can store files, the app needs write permissions to this location. The path should point to a directory that will be destroyed upon uninstallation.

◆ SetDefaultNavigationBarVisibility()

void CYIApp::SetDefaultNavigationBarVisibility ( CYIScreenProperty::NavigationBar  navigationBar)

◆ SetDefaultOrientation()

void CYIApp::SetDefaultOrientation ( CYIScreenProperty::Orientation  orientation)

◆ SetDefaultStatusBarVisibility()

void CYIApp::SetDefaultStatusBarVisibility ( CYIScreenProperty::StatusBar  statusbar)

◆ SetExternalPath()

void CYIApp::SetExternalPath ( const CYIString externalPath)

Specify the location to which the application can place persistent files. The path should point to a directory that is not destroyed upon uninstallation.

◆ SetHUDVisibility()

void CYIApp::SetHUDVisibility ( bool  visible)

Sets the visibility of the HUD.

See also
CYIHud

◆ SetMultiTouchEnabled()

void CYIApp::SetMultiTouchEnabled ( bool  enabled)

Specify if the application will be notified of multi-touch events. Multi touch events are disabled by default.

◆ SetRenderingThrottling()

void CYIApp::SetRenderingThrottling ( bool  bThrottle)

Sets whether rendering should be throttled. When throttled, the renderer will sleep to avoid exceeding 60fps.

Note
Some platforms internally limit the framerate, making throttling unnecessary.
Warning
Disabling throttling may result in higher-than-normal CPU usage.

◆ SetScreen()

bool CYIApp::SetScreen ( const CYIScreen screen)

◆ SetScreenProperties()

bool CYIApp::SetScreenProperties ( int  screenSizeX,
int  screenSizeY,
int  screenDensityX,
int  screenDensityY 
)

◆ SetShowFPS()

void CYIApp::SetShowFPS ( bool  show)

Enable FPS rendering

Deprecated:
This function has been deprecated and may be removed in a future release. SetHUDVisibility should be used instead.

◆ SetSurface()

bool CYIApp::SetSurface ( CYISurface pSurface)

◆ SetVersion()

void CYIApp::SetVersion ( const CYIString version)

Sets the application version string for this application object.

◆ SurfaceWasResized()

void CYIApp::SurfaceWasResized ( int32_t  width,
int32_t  height 
)

Handles available suface size changed notification. This will update the CYISurface and pass the notification along to the user.

See also
OnSurfaceSizeChanged

◆ Swap()

virtual void CYIApp::Swap ( )
virtual

This function will swap the contents of the back and front buffers and throttle the application's rendering to 60 frames per second. For double buffered rendering, this operation must be performed after drawing is complete. A typical frame will consist of an Update(), a Draw(), and a Swap() in that order.

◆ Update()

bool CYIApp::Update ( bool  forceDirty = false,
bool  updateTime = true 
)

This function updates all of the application logic and the scene tree. Rendering occurs in Draw(). Returns true if a redraw is required following the update.

forceDirty can be set to true to force a re-draw. This should only be done when absolutely necessary updateTime can be set to false to avoid a time update; this can be useful when an update cycle is desirable, but a time advance is not.

◆ UserConfiguration()

virtual CYIFrameworkConfiguration CYIApp::UserConfiguration ( )
virtual

Function will be called before initialization.

The user must implement the UserConfiguration() function and return a CYIFrameworkConfiguration object in order to set any configurable pre-initialization settings.

◆ UserInit()

virtual bool CYIApp::UserInit ( )
protectedpure virtual

This function will be called during app initialization.

◆ UserStart()

virtual bool CYIApp::UserStart ( )
protectedpure virtual

This is guaranteed to execute as the last component after all initializations are complete, including UserInit().

◆ UserUpdate()

virtual void CYIApp::UserUpdate ( )
inlineprotectedvirtual

Can be overridden by the user that will be called every time the application is updating its internal timers, animations and the scene tree.

Friends And Related Function Documentation

◆ CYIAppPriv

friend class CYIAppPriv
friend

◆ CYIFPSWidget

friend class CYIFPSWidget
friend

Member Data Documentation

◆ m_pPriv

CYIAppPriv* CYIApp::m_pPriv
protected

◆ SurfaceSizeChanged

CYISignal<int32_t , int32_t > CYIApp::SurfaceSizeChanged

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