You.i Engine
CYISceneManager Class Reference

Detailed Description

Scene trees composed of CYISceneNode objects are registered with the scene manager in order for them to be displayed to the user and so that they can receive inputs.

Scene trees are often loaded from layout files using LoadScene(), and then registered with the scene manager using AddScene(). At this point they are also staged meaning that they will be considered when the draw list is constructed during Update(). Scenes which are not staged do not receive inputs, views in those scenes may not receive focus, and those scenes will not be considered for rendering.

Loading a scene from a layout, and adding it to the scene manager:

CYISceneNode *pFullComposition = pSceneManager->LoadScene("FullComposition.layout");
pSceneManager->AddScene("fullcomp", pFullComposition);

When loading a scene certain properties of the scene must be defined. The scaling and alignment rules define how the scene adapts its designed dimensions to the dimensions at which it is being displayed. For instance, CYISceneManager::ScaleType::Stretch applied to a scene which is loaded at full-screen will naively stretch it to fit the dimensions of the display.

The return value from LoadScene() is a pointer to the root of the scene defined by the layout file provided. At this point individual elements are extracted using CYISceneNode::GetNode or CYISceneView::FindNode on the resultant scene root:

CYIListView *pListView = pFullComposition->GetNode<CYIListView>("FullList");
if (!m_pListView)
{
return false;
}

When adding a scene using AddScene() it is possible to display the scene in a sub-region of the screen. It is also possible to layer screens over top of one another by using layer indices. Scenes which are not full-screen and which are not the bottom-most layer should indicate that they are CYISceneManager::LayerType::Transparent, meaning that they can be drawn over other scenes.

Changes to focus are driven by the scene manager. The directional key events: CYIKeyEvent::ArrowUp, CYIKeyEvent::ArrowDown, CYIKeyEvent::ArrowLeft, and CYIKeyEvent::ArrowRight drive focus between views depending on their on-screen position and orientation. Additionally CYIEvent::Tab drives focus "forward" and "reverse" depending on left to right and top-down focus order, unless otherwise specified.

CYIEvent instances are driven through the CYIApp into the CYISceneManager for redirection to the appropriate location. Events of type CYIActionEvent, which are mouse and touch events, are offered to the scene tree using their spatial coordinates. These spatial coordinates are converted from window to world space and intersected with CYISceneNode bounding boxes until a target is found. The phase at which events are moving down the tree in search of a target is referred to as the "capture" phase. The completion of a "capture" marks the "at target" phase at which the event is handled by the target node. Following this is the "bubble" phase in which all ancestors of the target node are offered the event again.

#include <scenetree/YiSceneManager.h>

Inheritance diagram for CYISceneManager:

Public Types

enum  LayerType {
  LayerType::Opaque,
  LayerType::Transparent
}
 Specifies layering rules on a scene. Transparent scenes may be drawn over other scenes. More...
 
enum  ScaleType {
  ScaleType::Fill,
  ScaleType::Fit,
  ScaleType::Stretch,
  ScaleType::ActualSize,
  ScaleType::ResponsiveLayout
}
 Scaling rules define how the scene adapts to having different dimensions. More...
 
enum  VerticalAlignmentType {
  VerticalAlignmentType::Top,
  VerticalAlignmentType::Center,
  VerticalAlignmentType::Bottom
}
 Vertical alignment. More...
 
enum  HorizontalAlignmentType {
  HorizontalAlignmentType::Left,
  HorizontalAlignmentType::Center,
  HorizontalAlignmentType::Right
}
 Horizontal alignment. More...
 
enum  MissingClassHandlingMode {
  MissingClassHandlingMode::Abort,
  MissingClassHandlingMode::SwapWithSceneView
}
 Optional fallback rules for missing view types during scene loading. More...
 

Public Member Functions

 CYISceneManager (std::unique_ptr< CYIFocusEngine > pFocusEngine)
 
virtual ~CYISceneManager ()
 
std::unique_ptr< CYISceneViewCreateScene (const YI_RECT_REL &worldRegionOfInterest, ScaleType scaleType=ScaleType::Stretch, VerticalAlignmentType vAlign=VerticalAlignmentType::Center, HorizontalAlignmentType hAlign=HorizontalAlignmentType::Center)
 
std::unique_ptr< CYISceneViewLoadScene (const CYIString &filename, ScaleType scaleType=ScaleType::Stretch, VerticalAlignmentType vAlign=VerticalAlignmentType::Center, HorizontalAlignmentType hAlign=HorizontalAlignmentType::Center, MissingClassHandlingMode missingHandlingMode=MissingClassHandlingMode::Abort, CYICameraFactory cameraFactory=nullptr)
 
std::unique_ptr< CYISceneViewLoadScene (const CYIString &filename, const YI_RECT_REL &screenRegion, ScaleType scaleType=ScaleType::Stretch, VerticalAlignmentType vAlign=VerticalAlignmentType::Center, HorizontalAlignmentType hAlign=HorizontalAlignmentType::Center, MissingClassHandlingMode missingHandlingMode=MissingClassHandlingMode::Abort, CYICameraFactory cameraFactory=nullptr)
 
void UpdateScene (CYISceneView *pRoot)
 
void UpdateScene (CYISceneView *pRoot, ScaleType scaleType, VerticalAlignmentType vAlign, HorizontalAlignmentType hAlign)
 
void UpdateScene (CYISceneView *pRoot, const YI_RECT_REL &screenRegion, ScaleType scaleType=ScaleType::Stretch, VerticalAlignmentType align=VerticalAlignmentType::Center, HorizontalAlignmentType hAlign=HorizontalAlignmentType::Center)
 
void UpdateStagedScenes ()
 
void UpdateUnstagedScenes ()
 
void UpdateAllScenes ()
 
void UpdateBackground ()
 
void OnSurfaceSizeChanged ()
 
bool GetSceneUpdateProperties (CYISceneView *pRoot, ScaleType &scaleType, VerticalAlignmentType &vAlign, HorizontalAlignmentType &hAlign) const
 
bool AddScene (const CYIString &name, std::unique_ptr< CYISceneNode > pSceneNode, size_t layerIndex=0, LayerType layerType=LayerType::Opaque, const CYIViewport *pCustomViewport=nullptr)
 
std::unique_ptr< CYISceneNodeRemoveScene (CYISceneNode *pSceneNode)
 
std::unique_ptr< CYISceneNodeRemoveScene (const CYIString &name)
 
bool UpdateSceneProperties (const CYIString &name, LayerType layerType=LayerType::Opaque, const CYIViewport *pCustomViewport=nullptr)
 
bool GetSceneProperties (const CYIString &name, LayerType &layerType, CYIViewport &viewport) const
 
size_t GetStagedSceneCount () const
 
CYISceneNodeGetStagedScene (size_t index) const
 
CYISceneNodeGetStagedScene (const CYIString &name) const
 
std::vector< CYISceneNode * > GetStagedScenes () const
 
size_t GetUnstagedSceneCount () const
 
CYISceneNodeGetUnstagedScene (size_t index) const
 
CYISceneNodeGetUnstagedScene (const CYIString &name) const
 
std::vector< CYISceneNode * > GetUnstagedScenes () const
 
size_t GetSceneCount () const
 
CYISceneNodeGetScene (size_t index) const
 
CYISceneNodeGetScene (const CYIString &name) const
 
std::vector< CYISceneNode * > GetScenes () const
 
const CYIStringGetSceneName (CYISceneNode *pScene) const
 
void ShowScene (const CYIString &name)
 
void HideScene (const CYIString &name)
 
bool GetSceneLayerIndex (const CYIString &name, size_t &layerIndex)
 
bool SetSceneLayerIndex (const CYIString &name, size_t layerIndex)
 
bool StageScene (const CYIString &name)
 
bool UnstageScene (const CYIString &name)
 
bool IsSceneStaged (const CYIString &name) const
 
void DestroyScenes ()
 
bool Update (bool forceDirty, bool forceRender=false)
 
bool Layout (CYISceneNode *pNode)
 
void SetKeyboardCaptureNode (CYISceneNode *pNode)
 
CYISceneNodeGetKeyboardCaptureNode () const
 
void SetPointerCaptureNode (CYISceneNode *pNode, uint8_t pointerID)
 
CYISceneNodeGetPointerCaptureNode (uint8_t pointerID)
 
void SetTrackpadCaptureNode (CYISceneNode *pNode)
 
CYISceneNodeGetTrackpadCaptureNode () const
 
void SetEventCaptureRootNode (CYISceneNode *pNode)
 
CYISceneNodeGetEventCaptureRootNode ()
 
bool AddGlobalEventListener (CYIEvent::Type eventType, CYIEventHandler *pListener, CYIEventTarget::Phase phase=CYIEventTarget::Phase::Bubble)
 
bool RemoveGlobalEventListener (CYIEvent::Type eventType, CYIEventHandler *pListener, CYIEventTarget::Phase phase=CYIEventTarget::Phase::Bubble)
 
bool IsReachable (const CYISceneNode *pNode) const
 
CYISceneViewGetViewWithFocus () const
 
CYISceneViewGetViewWithFocus (const CYISceneNode *pRootNode) const
 
bool HasFocus (const CYISceneView *pView) const
 
bool RequestFocus (const CYISceneView *pViewToFocus, CYIFocus::FocusRootRule focusRootRule=CYIFocus::FocusRootRule::DescendantsUpdateContext)
 
bool MoveFocus (CYIFocus::Direction direction, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
 
void ClearFocus ()
 
bool CanBeFocused (const CYISceneView *pView) const
 
void QueueTimelineForPlayback (CYITimeline *pTimeline)
 
CYISceneNodeGetTargetNodeAtScreenLocation (int32_t screenX, int32_t screenY) const
 
void SetBackgroundColor (const CYIColor &color)
 
const CYIColorGetBackgroundColor ()
 
void SetDrawSkipEnabled (bool enabled)
 
bool IsDrawSkipEnabled () const
 
void RequestRerender ()
 
void SetPropertyChangeMonitor (IYIPropertyChangeMonitor *pMonitor)
 
IYIPropertyChangeMonitor * GetPropertyChangeMonitor ()
 
void SetEventMonitor (IYIEventMonitor *pMonitor)
 
IYIEventMonitor * GetEventMonitor ()
 
- Public Member Functions inherited from CYIEventHandler
 CYIEventHandler ()
 
 CYIEventHandler (const CYIEventHandler &)
 
virtual ~CYIEventHandler ()
 
CYIEventHandleroperator= (const CYIEventHandler &)
 
bool RegisterEventFilter (CYIEventFilter *pFilter)
 
bool UnregisterEventFilter (CYIEventFilter *pFilter)
 
bool PreFilter (const std::shared_ptr< CYIEventDispatcher > &pDispatcher, CYIEvent *pEvent)
 
bool PostFilter (const std::shared_ptr< CYIEventDispatcher > &pDispatcher, CYIEvent *pEvent)
 
bool AreEventsEnabled () const
 
void EnableEvents (bool enable)
 
- Public Member Functions inherited from CYISignalHandler
 CYISignalHandler ()
 
 CYISignalHandler (const CYISignalHandler &signalHandler)
 
virtual ~CYISignalHandler ()
 
CYISignalHandleroperator= (const CYISignalHandler &signalHandler)
 
void MoveToThread (CYIThread *pThread)
 This function allows the user to override the default thread affinity to any CYIThread that may or may not be running. More...
 
CYIThreadHandle GetThreadAffinity () const
 
void SetThreadAffinity (const CYIThreadHandle &threadAffinity)
 
virtual bool IsConnected () const
 
virtual bool IsConnected (const CYISignalBase &signal) const
 
void Disconnect (CYISignalBase &signal)
 
void DisconnectFromAllSignals ()
 
- Public Member Functions inherited from CYIThread::Listener
 Listener ()
 
virtual ~Listener ()
 
virtual void OnThreadStarted (CYIThread *)
 
virtual void OnThreadTerminated (CYIThread *)
 
virtual void OnThreadFinished (CYIThread *)
 

Public Attributes

CYISignal< const CYIString &, CYISceneNode * > SceneStaged
 
CYISignal< const CYIString &, CYISceneNode * > SceneUnstaged
 

Protected Member Functions

bool DispatchEvent (const std::shared_ptr< CYIEventDispatcher > &pDispatcher, CYIEvent *pEvent, CYISceneNode *pTarget)
 
bool DispatchSynthesizedActionEvent (const std::shared_ptr< CYIEventDispatcher > &pDispatcher, CYIEvent *pEvent, CYISceneNode *pTarget, CYIEvent::Type type)
 
virtual bool HandleEvent (const std::shared_ptr< CYIEventDispatcher > &pDispatcher, CYIEvent *pEvent) override
 

Friends

class CYIFocusPriv
 
class CYISceneManagerPriv
 
class CYISceneNodeUtilityPriv
 

Additional Inherited Members

- Protected Attributes inherited from CYIEventHandler
bool m_enableEvents
 

Member Enumeration Documentation

◆ HorizontalAlignmentType

Horizontal alignment.

Defines how the scene will be aligned on the horizontal axis, given the CYISceneManager::ScaleType. Specified when loading a scene using LoadScene().

Enumerator
Left 
Center 
Right 

◆ LayerType

Specifies layering rules on a scene. Transparent scenes may be drawn over other scenes.

When adding scenes, layering instructions are provided.

Generally, the bottom-most layer should be drawn opaquely with subsequent layers drawn transparently. If multiple scenes are present on screen using sub-regions, such as in the case of a split-screen view, then the bottom-most layer in each subregion should be opaque.

Enumerator
Opaque 

Will clear its viewport prior to regit diff ndering

Transparent 

Will draw without clearing its viewport

◆ MissingClassHandlingMode

Optional fallback rules for missing view types during scene loading.

CYISceneView subclasses are resolved during scene import in LoadScene(). Default behaviour will assert and fail scene import if the root is a view subclass that is not able to be resolved, due to missing definitions. This provides an optional fallback to the base CYISceneView. Subviews will follow the same behavior.

Enumerator
Abort 
SwapWithSceneView 

◆ ScaleType

Scaling rules define how the scene adapts to having different dimensions.

Scaling rules are applied during LoadScene() and define how a screen will adapt from its designed dimensions to its target dimensions.

Enumerator
Fill 

Maintains aspect ratio. The scene will be scaled to fill and possibly overflow the target dimensions, with extra content being cropped.

Fit 

Maintains aspect ratio. The scene will be scaled to fit inside the target dimensions, and will be letterboxed or pillarboxed inside of the region.

Stretch 

Does not maintain aspect ratio. The scene will be stretched to exactly fill the target dimensions.

ActualSize 

Maintains aspect ratio. The scene maintains its designed dimensions.

ResponsiveLayout 

Scales the content based on the responsive layout anchors found within. If no responsive layout anchors are found the composition will stretch.

◆ VerticalAlignmentType

Vertical alignment.

Defines how the scene will be aligned on the vertical axis, given the CYISceneManager::ScaleType. Specified when loading a scene using LoadScene().

Enumerator
Top 
Center 
Bottom 

Constructor & Destructor Documentation

◆ CYISceneManager()

CYISceneManager::CYISceneManager ( std::unique_ptr< CYIFocusEngine pFocusEngine)

◆ ~CYISceneManager()

virtual CYISceneManager::~CYISceneManager ( )
virtual

Member Function Documentation

◆ AddGlobalEventListener()

bool CYISceneManager::AddGlobalEventListener ( CYIEvent::Type  eventType,
CYIEventHandler pListener,
CYIEventTarget::Phase  phase = CYIEventTarget::Phase::Bubble 
)

The pListener will be notified of any eventType events occurring in the scene tree, during their phase, regardless of the target of the events. Returns false if the listener is null or is already registered.

See also
CYIEventTarget::AddEventListener

◆ AddScene()

bool CYISceneManager::AddScene ( const CYIString name,
std::unique_ptr< CYISceneNode pSceneNode,
size_t  layerIndex = 0,
LayerType  layerType = LayerType::Opaque,
const CYIViewport pCustomViewport = nullptr 
)

The pSceneNode, often previously loaded via LoadScene(), is registered with the scene manager with the given name and becomes eligible for rendering, input handling, and staging and unstaging.

Note
The scene is unstaged by default.

pSceneNode must not have a parent and it must have a render target. Failure to meet these conditions results in pSceneNode being deleted and false being returned.

If other scenes have been added this scene will draw above or below them based on its layerIndex. A layerIndex of 1 will draw on top of an index of 0. If there are existing scenes with the same layer index, they will be drawn in the order they were staged.

layerType determines whether anything will visually appear beneath the scene in layer order. Scenes which have a higher layerIndex must often specify CYISceneManager::LayerType::Transparent, unless they are full-screen and opaque.

The scene can be displayed in pCustomViewport which is a rectangular region specified in window coordinates, where (0,0) is the bottom-left of the window.

Note
If all scenes registered in the scene manager are CYISceneManager::LayerType::Transparent and every pixel on the screen is not drawn with full opacity at some point during the rendering, then the previous contents of the screen buffer will appear.
The scene manager takes ownership of pSceneNode.

◆ CanBeFocused()

bool CYISceneManager::CanBeFocused ( const CYISceneView pView) const

Returns true if the given view can receive focus.

In order to receive focus a view must be reachable, have its visibility set to true, and be set to focusable.

See also
CYISceneView::IsFocusable
CYISceneNode::IsTrulyVisible
CYISceneManager::IsReachable

◆ ClearFocus()

void CYISceneManager::ClearFocus ( )

Clears the currently focused view, if any.

◆ CreateScene()

std::unique_ptr<CYISceneView> CYISceneManager::CreateScene ( const YI_RECT_REL worldRegionOfInterest,
ScaleType  scaleType = ScaleType::Stretch,
VerticalAlignmentType  vAlign = VerticalAlignmentType::Center,
HorizontalAlignmentType  hAlign = HorizontalAlignmentType::Center 
)

Creates an empty scene that encompasses the whole window, and into which content can be placed.

The provided worldRegionOfInterest describes the region which will be visible by the perspective camera viewing the scene, with (0,0) being in the top-left direction. Items added to this scene need to be sized and located according to this region of interest.

Aspect ratio differences between the worldRegionOfInterest and the screen dimensions will be resolved according to scaleType, and the subsequent result will be aligned into the available space according to vAlign and hAlign.

◆ DestroyScenes()

void CYISceneManager::DestroyScenes ( )

Destroys all scenes and clears the staged and un-staged collections.

◆ DispatchEvent()

bool CYISceneManager::DispatchEvent ( const std::shared_ptr< CYIEventDispatcher > &  pDispatcher,
CYIEvent pEvent,
CYISceneNode pTarget 
)
protected

Send an event to the specified target (and its ancestors). Applies the CYIEventTarget::Phase::Capture and CYIEventTarget::Phase::Bubble phases.

◆ DispatchSynthesizedActionEvent()

bool CYISceneManager::DispatchSynthesizedActionEvent ( const std::shared_ptr< CYIEventDispatcher > &  pDispatcher,
CYIEvent pEvent,
CYISceneNode pTarget,
CYIEvent::Type  type 
)
protected

◆ GetBackgroundColor()

const CYIColor& CYISceneManager::GetBackgroundColor ( )

Returns the current background color.

See also
SetBackgroundColor

◆ GetEventCaptureRootNode()

CYISceneNode* CYISceneManager::GetEventCaptureRootNode ( )

Returns the node that has been set as the capture node for all events using SetEventCaptureRootNode(), or null if no node is capturing events.

◆ GetEventMonitor()

IYIEventMonitor* CYISceneManager::GetEventMonitor ( )

◆ GetKeyboardCaptureNode()

CYISceneNode* CYISceneManager::GetKeyboardCaptureNode ( ) const

Returns the node which is currently capturing all keyboard events, or null if there is no capture node.

◆ GetPointerCaptureNode()

CYISceneNode* CYISceneManager::GetPointerCaptureNode ( uint8_t  pointerID)

Returns the node that has been set as the capture node for pointerID using SetPointerCaptureNode(), or null if no node is capturing it.

◆ GetPropertyChangeMonitor()

IYIPropertyChangeMonitor* CYISceneManager::GetPropertyChangeMonitor ( )

◆ GetScene() [1/2]

CYISceneNode* CYISceneManager::GetScene ( size_t  index) const

Returns the scene at the zero based index index, or null if index is greater than or equal to the number of scenes.

See also
GetSceneCount()
Note
The scene manager retains ownership of the returned scene node.
Warning
The index of scenes may change as scenes are added, removed, staged, and unstaged.

◆ GetScene() [2/2]

CYISceneNode* CYISceneManager::GetScene ( const CYIString name) const

Returns a scene, previously added by AddScene(), with the given name, or null if it is not found.

Note
The scene manager retains ownership of the returned scene node.

◆ GetSceneCount()

size_t CYISceneManager::GetSceneCount ( ) const

Returns the number of scenes which have been added using AddScene(), both staged and unstaged.

◆ GetSceneLayerIndex()

bool CYISceneManager::GetSceneLayerIndex ( const CYIString name,
size_t layerIndex 
)

Returns the layer index of the scene node named by name. Returns false if name does not name a root scene node.

◆ GetSceneName()

const CYIString& CYISceneManager::GetSceneName ( CYISceneNode pScene) const

Returns the name of pScene in the scene manager. If pScene wasn't added to the scene manager returns an empty string.

◆ GetSceneProperties()

bool CYISceneManager::GetSceneProperties ( const CYIString name,
LayerType layerType,
CYIViewport viewport 
) const

Retrieves the properties of a scene specified by name.

Returns false if no scene named name has been added.

The values of layerType and viewport are set to the properties of this scene.

◆ GetScenes()

std::vector<CYISceneNode *> CYISceneManager::GetScenes ( ) const

Returns all scenes in the scene manager.

See also
GetStagedScenes()
GetUnstagedScenes()
Note
The scene manager retains ownership of the returned scene nodes.

◆ GetSceneUpdateProperties()

bool CYISceneManager::GetSceneUpdateProperties ( CYISceneView pRoot,
ScaleType scaleType,
VerticalAlignmentType vAlign,
HorizontalAlignmentType hAlign 
) const

Retrieves the current scale, vertical alignment and horizontal alignment set on the scene pointed to by pRoot. Returns true if the scene's update properties have been set by a previous call to UpdateScene() or LoadScene(). Returns false if the scene's update properties have not yet been set.

Note
If this method returns false the default scene update properties will be supplied.
See also
LoadScene(const CYIString &filename, const YI_RECT_REL &screenRegion, ScaleType scaleType, VerticalAlignmentType align, HorizontalAlignmentType hAlign, MissingClassHandlingMode, CYICameraFactory);
UpdateScene(CYISceneView *pRoot, const YI_RECT_REL &screenRegion, ScaleType scaleType, VerticalAlignmentType align, HorizontalAlignmentType hAlign)

◆ GetStagedScene() [1/2]

CYISceneNode* CYISceneManager::GetStagedScene ( size_t  index) const

Returns the staged scene at the zero based index index, or null if index is greater than or equal to the number of staged scenes.

See also
GetStagedSceneCount()
Note
The scene manager retains ownership of the returned scene node.
Warning
The index of scenes may change as scenes are added, removed, staged, and unstaged.

◆ GetStagedScene() [2/2]

CYISceneNode* CYISceneManager::GetStagedScene ( const CYIString name) const

Returns the staged scene matching the name provided, or null if it is not found.

Note
The scene manager retains ownership of the returned scene node.

◆ GetStagedSceneCount()

size_t CYISceneManager::GetStagedSceneCount ( ) const

Returns the number of scenes which have been staged using StageScene().

◆ GetStagedScenes()

std::vector<CYISceneNode *> CYISceneManager::GetStagedScenes ( ) const

Returns all of the currently staged scenes.

See also
GetScenes()
GetUnstagedScenes()
Note
The scene manager retains ownership of the returned scene nodes.

◆ GetTargetNodeAtScreenLocation()

CYISceneNode* CYISceneManager::GetTargetNodeAtScreenLocation ( int32_t  screenX,
int32_t  screenY 
) const

Returns the node located at the provided screen-space location. Returns null if there is no node present at the given location, or if the global CYIRenderingSurfaceInfo is not valid. The location is relative to the top-left of the screen.

See also
CYIApp::GetRenderingSurfaceInfo
CYIRenderingSurfaceInfo::IsValid

◆ GetTrackpadCaptureNode()

CYISceneNode* CYISceneManager::GetTrackpadCaptureNode ( ) const

Returns the node which is currently capturing all trackpad events, or null if there is no capture node.

◆ GetUnstagedScene() [1/2]

CYISceneNode* CYISceneManager::GetUnstagedScene ( size_t  index) const

Returns the unstaged scene at the zero based index index, or null if index is greater than or equal to the number of unstaged scenes.

See also
GetUnstagedSceneCount()
Note
The scene manager retains ownership of the returned scene node.
Warning
The index of scenes may change as scenes are added, removed, staged, and unstaged.

◆ GetUnstagedScene() [2/2]

CYISceneNode* CYISceneManager::GetUnstagedScene ( const CYIString name) const

Returns the unstaged scene matching the name provided, or null if it is not found.

Note
The scene manager retains ownership of the returned scene node.

◆ GetUnstagedSceneCount()

size_t CYISceneManager::GetUnstagedSceneCount ( ) const

Returns the number of scenes which have been added using AddScene() but have been unstaged with UnstageScene().

◆ GetUnstagedScenes()

std::vector<CYISceneNode *> CYISceneManager::GetUnstagedScenes ( ) const

Returns all of the currently unstaged scenes.

See also
GetScenes()
GetStagedScenes()
Note
The scene manager retains ownership of the returned scene nodes.

◆ GetViewWithFocus() [1/2]

CYISceneView* CYISceneManager::GetViewWithFocus ( ) const

Returns the view that currently has focus, or null if no view has focus.

◆ GetViewWithFocus() [2/2]

CYISceneView* CYISceneManager::GetViewWithFocus ( const CYISceneNode pRootNode) const

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

Returns the view that currently has focus only if it is in the tree under and including pRootNode.

◆ HandleEvent()

virtual bool CYISceneManager::HandleEvent ( const std::shared_ptr< CYIEventDispatcher > &  pDispatcher,
CYIEvent pEvent 
)
overrideprotectedvirtual

Scene manager event handling. Does not bubble down to the collection of root scene nodes.

Implements CYIEventHandler.

◆ HasFocus()

bool CYISceneManager::HasFocus ( const CYISceneView pView) const

◆ HideScene()

void CYISceneManager::HideScene ( const CYIString name)

Hide a root node by name.

◆ IsDrawSkipEnabled()

bool CYISceneManager::IsDrawSkipEnabled ( ) const

Returns true if Draw Skip is enabled.

See also
SetDrawSkipEnabled

◆ IsReachable()

bool CYISceneManager::IsReachable ( const CYISceneNode pNode) const

Returns true if this pNode is present in a staged scene.

◆ IsSceneStaged()

bool CYISceneManager::IsSceneStaged ( const CYIString name) const

Returns true if a scene with name is staged.

◆ Layout()

bool CYISceneManager::Layout ( CYISceneNode pNode)

Performs a layout pass on the scene node subtree starting at pNode. Returns true if the scene tree requires a redraw.

Note
If the subtree starting at pNode is dirty after the layout pass, CYISceneNode::Update() is called on the subtree.
This function cannot be called while a layout pass is in progress. Doing so results in a warning being logged and in the function returning false immediately.

◆ LoadScene() [1/2]

std::unique_ptr<CYISceneView> CYISceneManager::LoadScene ( const CYIString filename,
ScaleType  scaleType = ScaleType::Stretch,
VerticalAlignmentType  vAlign = VerticalAlignmentType::Center,
HorizontalAlignmentType  hAlign = HorizontalAlignmentType::Center,
MissingClassHandlingMode  missingHandlingMode = MissingClassHandlingMode::Abort,
CYICameraFactory  cameraFactory = nullptr 
)

Loads a composition into the scene. Returns null in case of failure.

The layout at filename will be loaded using scaleType scaling rules and hAlign, align alignment into a full-screen region. The dimensions of the fullscreen region are determined at the time of the call. On platforms where the screen dimensions can be modified such as in portrait-to-landscape orientation changes, LoadScene() must be called in the correct orientation.

missingHandlingMode describes an optional fallback if the root scene view has a view specialization that cannot be resolved due to missing definitions or bad assets. cameraFactory is a function which will be called to create the default scene camera if no camera information is found in the composition. If no factory is supplied and no camera exists in the composition a default CYIPerspectiveCameraSceneNode will be created.

◆ LoadScene() [2/2]

std::unique_ptr<CYISceneView> CYISceneManager::LoadScene ( const CYIString filename,
const YI_RECT_REL screenRegion,
ScaleType  scaleType = ScaleType::Stretch,
VerticalAlignmentType  vAlign = VerticalAlignmentType::Center,
HorizontalAlignmentType  hAlign = HorizontalAlignmentType::Center,
MissingClassHandlingMode  missingHandlingMode = MissingClassHandlingMode::Abort,
CYICameraFactory  cameraFactory = nullptr 
)

Loads a composition into the scene. Returns null in case of failure.

The layout at filename will be loaded using scaleType scaling rules and hAlign, align alignment into a full-screen region. The dimensions of the fullscreen region are determined at the time of the call. On platforms where the screen dimensions can be modified such as in portrait-to-landscape orientation changes, LoadScene() must be called in the correct orientation.

missingHandlingMode describes an optional fallback if the root scene view has a view specialization that cannot be resolved due to missing definitions or bad assets. cameraFactory is a function which will be called to create the default scene camera if no camera information is found in the composition. If no factory is supplied and no camera exists in the composition a default CYIPerspectiveCameraSceneNode will be created.

The screenRegion defines the size and location of the scene to be loaded. screenRegion's origin is the bottom-left of the window.

See also
LoadScene(const CYIString &, ScaleType, VerticalAlignmentType, HorizontalAlignmentType, MissingClassHandlingMode, CYICameraFactory).

◆ MoveFocus()

bool CYISceneManager::MoveFocus ( CYIFocus::Direction  direction,
const CYIFocusSearchOptions options = CYIFocusSearchOptions() 
)

'Moves' the focus in direction direction, relative to the view that currently has focus. If no view currently has focus, a focus search is started from the current focus root.

options can be used to further restrict the set of valid focus candidates.

Returns true if focus was successfully moved.

◆ OnSurfaceSizeChanged()

void CYISceneManager::OnSurfaceSizeChanged ( )

Updates all scenes, updates the background, and sends a CYIEvent::Type::ActionLeave event to all recipients of CYIEvent::Type::ActionMove or CYIEvent::Type::ActionDown if they have not received one already.

See also
UpdateAllScenes
UpdateBackground

◆ QueueTimelineForPlayback()

void CYISceneManager::QueueTimelineForPlayback ( CYITimeline pTimeline)

Queues a CYITimeline object for playback on the UI thread. Calling this function on the UI thread will cause the timeline to be played back during the next draw cycle.

◆ RemoveGlobalEventListener()

bool CYISceneManager::RemoveGlobalEventListener ( CYIEvent::Type  eventType,
CYIEventHandler pListener,
CYIEventTarget::Phase  phase = CYIEventTarget::Phase::Bubble 
)

The pListener will no longer be a global event listener. Returns false if the listener was not registered with AddGlobalEventListener().

See also
CYIEventTarget::RemoveEventListener

◆ RemoveScene() [1/2]

std::unique_ptr<CYISceneNode> CYISceneManager::RemoveScene ( CYISceneNode pSceneNode)

Removes a scene which was previously added with AddScene(). Returns a null pointer if the scene has not been added.

See also
AddScene(const CYIString &, std::unique_ptr<CYISceneNode>, size_t, LayerType, const CYIViewport *)

◆ RemoveScene() [2/2]

std::unique_ptr<CYISceneNode> CYISceneManager::RemoveScene ( const CYIString name)

Removes a scene with name which was previously added with AddScene(). Returns a null pointer if no such named scene is found.

◆ RequestFocus()

bool CYISceneManager::RequestFocus ( const CYISceneView pViewToFocus,
CYIFocus::FocusRootRule  focusRootRule = CYIFocus::FocusRootRule::DescendantsUpdateContext 
)

Requests that pViewToFocus receive focus. The view will receive focus if it is focusable. Returns true if pViewToFocus obtained focus or had focus before the request.

For a view to take focus, it must meet the following requirements: it is visible, attached to the tree, and focusable.

focusRootRule dictates whether the focus system will allow the focus request to move to a view outside of the current focus root. When CYIFocus::FocusRootRule::DescendantsUpdateContext is provided this method will return true if pViewToFocus's focus root is updated with pViewToFocus as the current focus in that context.

pViewToFocus must be non-null. If focus needs to be cleared, ClearFocus can be used.

See also
CYISceneView::RequestFocus

◆ RequestRerender()

void CYISceneManager::RequestRerender ( )

Causes the scene to be redrawn during the next frame. This can be used to force a redraw when GPU assets are modified directly.

◆ SetBackgroundColor()

void CYISceneManager::SetBackgroundColor ( const CYIColor color)

Sets the solid background color which will be visible behind all scenes.

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

Note
This background color will only be visible behind the bottom-most scene if the scene was added with a layer type of CYISceneManager::LayerType::Transparent. If the scene was added with a layer type of CYISceneManager::LayerType::Opaque the scene's background color will be visible instead.

◆ SetDrawSkipEnabled()

void CYISceneManager::SetDrawSkipEnabled ( bool  enabled)

Enables or disabled draw skip. When enabled, draw skip will avoid drawing when no changes have been made to the scene tree.

◆ SetEventCaptureRootNode()

void CYISceneManager::SetEventCaptureRootNode ( CYISceneNode pNode)

pNode will capture all events.

Note
The scene manager does not take ownership of pNode.

◆ SetEventMonitor()

void CYISceneManager::SetEventMonitor ( IYIEventMonitor *  pMonitor)

Set the application Event Monitor which will send notifications for certain events.

Note
If no Monitor is set no notifications will be sent.

◆ SetKeyboardCaptureNode()

void CYISceneManager::SetKeyboardCaptureNode ( CYISceneNode pNode)

pNode will receive all keyboard events. There may only be one keyboard capture node at a time. The previous node, if any, will no longer capture keyboard events.

Note
The scene manager does not take ownership of pNode.

◆ SetPointerCaptureNode()

void CYISceneManager::SetPointerCaptureNode ( CYISceneNode pNode,
uint8_t  pointerID 
)

pNode will capture all action events from pointerID. There may only be one pointer capture node at a time. The previous node, if any, will no longer capture pointer events.

Note
The scene manager does not take ownership of pNode.
See also
CYIActionEvent::m_pointerID

◆ SetPropertyChangeMonitor()

void CYISceneManager::SetPropertyChangeMonitor ( IYIPropertyChangeMonitor *  pMonitor)

Set the application PropertyChangeMonitor which will track node property changes.

Note
If no Monitor is set node changes will be ignored.

◆ SetSceneLayerIndex()

bool CYISceneManager::SetSceneLayerIndex ( const CYIString name,
size_t  layerIndex 
)

Sets the layer index of the scene named name to the new layerIndex. Scenes are drawn back to front starting at layer index 0, so larger indices are drawn after smaller indices.

Returns false if name does not name a root scene node.

See also
AddScene(const CYIString &, std::unique_ptr<CYISceneNode>, size_t, LayerType, const CYIViewport *)

◆ SetTrackpadCaptureNode()

void CYISceneManager::SetTrackpadCaptureNode ( CYISceneNode pNode)

pNode will receive all trackpad events. There may only be one trackpad capture node at a time. The previous node, if any, will no longer capture trackpad events.

Note
The scene manager does not take ownership of pNode.

◆ ShowScene()

void CYISceneManager::ShowScene ( const CYIString name)

Show a root node by name.

◆ StageScene()

bool CYISceneManager::StageScene ( const CYIString name)

Stages a scene with name that has been registered to the scene manager with AddScene(). Staged scenes will be drawn and are eligible for inputs and focus events.

Returns false if no scene with name is registered or if the scene is already staged.

◆ UnstageScene()

bool CYISceneManager::UnstageScene ( const CYIString name)

Unstages a scene with name that has been registered to the scene manager with AddScene(). Unstaged scenes will not be drawn and are ineligible for inputs and focus events.

Returns false if the scene is not staged.

◆ Update()

bool CYISceneManager::Update ( bool  forceDirty,
bool  forceRender = false 
)

Drives changes to the scene tree, layouts, and focus within the scenes. Sending true for forceDirty causes a complete update regardless of the scene tree's dirty state. Setting true for forceRender causes a re-generation of the draw list regardless of the scene tree's dirty state.

Returns true if the scene tree requires a redraw.

◆ UpdateAllScenes()

void CYISceneManager::UpdateAllScenes ( )

Updates all scenes managed by the scene manager using the current surface rectange and the scale, vertical alignment and horizontal alignment specified previously by LoadScene() or UpdateScene(). If these have not previously been called the default values of CYISceneManager::ScaleType::Stretch, CYISceneManager::VerticalAlignmentType::Center and CYISceneManager::HorizontalAlignmentType::Center will be used.

See also
UpdateScene(CYISceneView*, ScaleType, VerticalAlignmentType, HorizontalAlignmentType)

◆ UpdateBackground()

void CYISceneManager::UpdateBackground ( )

Updates the background for the current surface size. This can be called when the surface size changes to update the background to match the current surface without updating all scenes.

See also
OnSurfaceSizeChanged

◆ UpdateScene() [1/3]

void CYISceneManager::UpdateScene ( CYISceneView pRoot)

Updates an existing scene using the current surface rectangle and the scale, vertical alignment and horizontal alignment specified previously by LoadScene or UpdateScene. If these have not previously been called the default values of CYISceneManager::ScaleType::Stretch, CYISceneManager::VerticalAlignmentType::Center and CYISceneManager::HorizontalAlignmentType::Center will be used.

See also
UpdateScene(CYISceneView*, ScaleType, VerticalAlignmentType, HorizontalAlignmentType)
UpdateScene(CYISceneView*, const YI_RECT_REL &, ScaleType, VerticalAlignmentType, HorizontalAlignmentType)

◆ UpdateScene() [2/3]

void CYISceneManager::UpdateScene ( CYISceneView pRoot,
ScaleType  scaleType,
VerticalAlignmentType  vAlign,
HorizontalAlignmentType  hAlign 
)

◆ UpdateScene() [3/3]

void CYISceneManager::UpdateScene ( CYISceneView pRoot,
const YI_RECT_REL screenRegion,
ScaleType  scaleType = ScaleType::Stretch,
VerticalAlignmentType  align = VerticalAlignmentType::Center,
HorizontalAlignmentType  hAlign = HorizontalAlignmentType::Center 
)

◆ UpdateSceneProperties()

bool CYISceneManager::UpdateSceneProperties ( const CYIString name,
LayerType  layerType = LayerType::Opaque,
const CYIViewport pCustomViewport = nullptr 
)

Updates the properties of a scene that has already been added. name specifies the name of the scene to update.

Returns false if no scene named name has been added.

Note
This method overwrites the scene render target attributes.
See also
AddScene()

◆ UpdateStagedScenes()

void CYISceneManager::UpdateStagedScenes ( )

Updates all staged scenes using the current surface rectange and the scale, vertical alignment and horizontal alignment specified previously by LoadScene() or UpdateScene(). If these have not previously been called the default values of CYISceneManager::ScaleType::Stretch, CYISceneManager::VerticalAlignmentType::Center and CYISceneManager::HorizontalAlignmentType::Center will be used.

See also
UpdateScene(CYISceneView*, ScaleType, VerticalAlignmentType, HorizontalAlignmentType)

◆ UpdateUnstagedScenes()

void CYISceneManager::UpdateUnstagedScenes ( )

Updates all un-staged scenes using the current surface rectange and the scale, vertical alignment and horizontal alignment specified previously by LoadScene() or UpdateScene(). If these have not previously been called the default values of CYISceneManager::ScaleType::Stretch, CYISceneManager::VerticalAlignmentType::Center and CYISceneManager::HorizontalAlignmentType::Center will be used.

See also
UpdateScene(CYISceneView*, ScaleType, VerticalAlignmentType, HorizontalAlignmentType)

Friends And Related Function Documentation

◆ CYIFocusPriv

friend class CYIFocusPriv
friend

◆ CYISceneManagerPriv

friend class CYISceneManagerPriv
friend

◆ CYISceneNodeUtilityPriv

friend class CYISceneNodeUtilityPriv
friend

Member Data Documentation

◆ SceneStaged

CYISignal<const CYIString &, CYISceneNode *> CYISceneManager::SceneStaged

Emitted when a scene is staged. The first signal parameter is the scene name, and the second is the root node of the scene.

◆ SceneUnstaged

CYISignal<const CYIString &, CYISceneNode *> CYISceneManager::SceneUnstaged

Emitted when a scene is unstaged. The first signal parameter is the scene name, and the second is the root node of the scene.


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