You.i Engine
Scene Tree

Detailed Description

Hierarchically organized elements used in rendering, defining spatial and logical relationships.

CYISceneNode is the basis for all scene tree elements in You.i Engine. It provides parent / child relationships, drawing order relationships, a spatial transformation hierarchy, and inherited properties related to: clipping, opacity, and visibility.

CYIRenderer consumes data from the CYISceneManager in order to render the contents of a scene on screen. Changes to how things appear on screen are driven by scene tree manipulation.

CYISceneView and its derived classes are also scene nodes, meaning that all visual components in You.i Engine can be part of a scene and can be manipulated in 3-dimensional space.

Typically a scene tree is constructed using CYISceneManager::LoadScene which loads a provided view template file and constructs the scene tree defined within. This tree can then be manipulated by finding nodes by their name or ID using CYISceneNode::GetNode, and modifying their properties or modifying the scene tree structure itself.

Spatial Transformations

Transformation matrices

A CYISceneNode is spatially positioned and oriented by modification of its position, rotation, orientation, scale, and anchor point values. These are interfaces to provide semantic meaning to the underlying transformation matrix. These properties are processed into a transformation matrix accessible by CYISceneNode::GetLocalTransform. This "local transformation" matrix describes how all descendant nodes will be affected by this node's spatial properties.

Coordinate Spaces

You.i Engine defines several coordinate spaces.

Local space

The local space of a node describes the coordinate system in which its children reside. If a node: pParent has two children: pNode1 and pNode2, the positions and rotations of pNode1 and pNode2 are expressed in the local space of pParent. That is, if pNode1 is at position (0, 10, 0) and pNode2 is at position (0, 0, 0), pNode1 is 10 units apart from pNode2 on the y-axis. On-screen, the relative location of pNode1 and pNode2 to each other rely on other transformations.

World space

The world space of a node describes the coordinate system in which all nodes in the scene tree reside. The world transform of a node is the concatenation of all of the local transformations of the node's ancestors, including itself. World space allows for a common spatial language across nodes belonging to the same scene. Continuing the example above, if pParent had a scale factor on it of (0, 2, 0) and pParent was the root of the scene, pNode1 and pNode2 can be said to be 20 units apart on the y-axis in world space.

Eye/Camera space

A scene tree loaded from a view template using CYISceneManager::LoadScene contains CYISceneNode derivatives of type CYIAbstractCameraSceneNode. These are nodes whose position in the scene describes the viewpoint of the user. A node's position in camera space is its location relative to the camera with which it is being drawn. If, in our above example, pCamera were a node located at (0, 5, 0) with "up" vector (0, 1, 0) then pNode1 would be 5 units above the camera, and pNode2 would be 5 units below it.

Screen space

Lastly, screen-space is the coordinate system described in pixels starting at (0,0) in the bottom-left corner of the screen. Screen space requires the addition of a CYIRenderTarget, which can be assigned to a CYISceneNode using CYISceneNode::SetRenderTarget. The render target determines the viewport, which is the screen-space rectangle into which all of the things in that sub-tree will render.

Clipping

A node's clipping box represents a region outside of which nothing will be drawn, it is specified on a node using CYISceneNode::SetClippingBox, but more commonly it is applied through You.i Engine After Effects Plug-in's properties panel. Regardless of how clipping is enabled, it's important to note that clipping is applied on all descendants of the node which contains clipping. If multiple nodes along a lineage enable clipping, the clipping boxes are intersected as they are accumulated to ensure the expected visual result.

Opacity

Opacity is a value representing how see-through a node and its descendants appear on screen, expressed between 0.0 (completely see-through) and 1.0 (completely opaque). While also inherited, the effective "composite" opacity can be queried at every level of the tree. CYISceneNode::GetLocalOpacity represents the node's own opacity, the opacity factor which it is applying to the final computation, and CYISceneNode::GetCompositeOpacity represents the cumulative opacity with which the node will be drawn.

Visibility

Visibility is a boolean value which represents whether the node and its descendants are visible on screen. Like opacity, visibility is inherited but can be checked both locally with CYISceneNode::IsVisible, indicating that the node itself is visible, and CYISceneNode::IsTrulyVisible indicating that the node and all of its ancestors are visible.

Classes

class  CYIAABB
 This class represents an Axis-Aligned Bounding Box. More...
 
class  CYIAbstractCameraSceneNode
 Provides a base for the definition of camera objects. More...
 
struct  CYIComponentPoolUID
 An identifier for an element in a CYIComponentPool object. More...
 
class  CYIImageSceneNode
 Provides special resize behaviour typically useful for images. More...
 
class  CYIOrthographicCameraSceneNode
 
class  CYIPerspectiveCameraSceneNode
 
class  CYISceneManager
 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. More...
 
class  CYISceneNode
 A scene node is the base type for all nodes which are used by the scene manager; it is an integral part of You.i Engine and is used extensively by various parts of the framework. More...
 
class  CYISceneNodeProxy
 A class used to proxy access to a CYISceneNode. More...
 
class  CYISpriteSceneNode
 Specialized CYISceneNode implementing a sprite. More...
 
class  CYITransform
 Provides transformation APIs. More...
 
struct  CYITransformComponent
 A minimal transform component. More...
 
class  CYITransformSystem
 The transform system maintains a component pool of CYITransformComponent data. More...
 
class  CYIVectorCanvasNode
 A scene node used to draw vector graphics. More...
 

Variables

const uint8_t YI_MAX_POINTER_ID = 10
 
const int32_t YI_DELAYED_DOWN_EVENT_DELAY = 115
 
const int32_t YI_LONG_PRESS_DELAY = 1000
 
const int32_t YI_LONG_PRESS_MOVE_TOLERANCE = 10
 

Variable Documentation

const int32_t YI_DELAYED_DOWN_EVENT_DELAY = 115
const int32_t YI_LONG_PRESS_DELAY = 1000
const int32_t YI_LONG_PRESS_MOVE_TOLERANCE = 10
const uint8_t YI_MAX_POINTER_ID = 10