Elements

Scene graph nodes. More...

Classes
class	iv::Align
	Container providing special behaviors related to relative alignment of its child. More...
class	iv::Border
	Container that adds margins around child, allowing wide variety of positioning options inside parent. More...
class	iv::DividerSlot
	A Slot that can be placed inside a Divider. More...
class	iv::Divider
	Container that divides its space between children according to their priorities. More...
class	iv::FixedOrder_Camera
	Scene root that renders items in fixed order, no Z sorting. More...
class	iv::Image
	Basic element that displays a texture. Has many optional configuration parameters. More...
class	iv::Prefsize
	Container that can override preferred size of its child. More...
class	iv::Slot
	Container that can put multiple SlotChild objects in one place. More...
class	iv::Transform
	Container that allows us to directly modify model matrix of its child. Usable both in UI compositing and in world views. More...
class	iv::Text
	Basic text element, needs to be supplied font path. More...
class	iv::TextLayout
	Container and layout manager for TextSegment objects. More...
class	iv::LumaButton
	Flexible base for variously styled buttons that needs to be supplied multiple textures. More...
class	iv::LumaFrame
	A window-like scrollable frame that needs to be supplied a texture. More...
class	iv::LumaScroller
	Vertical scroller with simple graphics. More...
class	iv::LumaText
	Text with theme-defined font and color. More...
class	iv::Rectangle_LumaButton
	Simple rectangular button. More...
class	iv::SimpleSplash
	Splash screen that is visible during loading times. More...

Detailed Description

Scene graph nodes.

About

This group contains classes that can be directly used in scene graph. It does not contain abstract and other incomplete classes.

Root of scene graph can be any class that inherits iv::Camera - currently only iv::FixedOrder_Camera. Children are added to scene using iv::OneChildElem::createChild and similar methods. Some Elements act as containers, some are renderable. Most common type of parent / child relationship is iv::Slot / iv::SlotChild, but there is also iv::Divider / iv::DividerSlot and iv::TextLayout and iv::TextSegment and more can be implemented if needed.

Example usage

iv::FixedOrder_Camera * camera;
 
void init( iv::Instance * inst )
{
    // instantiate scene root
    camera = new iv::FixedOrder_Camera( inst, iv::RenderTarget::Geometry( iv::float2( 1366, 768 ), 1.0 ) );
    
    // lifetime of subelements created using createChild will be tied to lifetime of camera
    auto border = camera->createChild< iv::Border >();   // iv::Border without changed attributes will position its content to the center without resizing it if not necessary.
    auto image = border->createChild< iv::Image >()
                    ->filename( "/ivorium_graphics/generic/stone.png" );
}
 
void render()
{
    camera->render_scene();
}
 
void deinit()
{
    delete camera;
}

About scene tree pre-render refresh

Each frame, before all the renderables are rendered, whole scene tree is traversed and all values are updated. This refresh has three stages: down-phase of first pass, up-phase of first pass and second pass.

1. Down-phase of first pass is not that important, it mainly refreshes iv::SlotChild::expectedSize which is not used by many Elements. Tree is traversed from root to children.
2. Up-phase of first pass aggregates so called synthesized parameters. It is mainly iv::SlotChild::preferredSize which is used by containers to resize their layouts. Tree is traversed from children to root in this stage. Renderable Elements also assign themselves to render queue in this stage (they must register each frame).
3. In second pass, containers assign so called inherited parameters to their children. Best example of such parameter is iv::SlotChild::size. Tree is traversed from root to children again. The second pass is not called each frame on each Element, Elements have to request second pass during first pass using iv::ElementRenderer::QueueSecondPass and then call iv::ElementRenderer::DequeueSecondPass during second pass.

Most attributes used in scene tree are iv::DirtyAttr. Apart from given value, it contains dirty flag that is set to true each time value is modified. That can be used to optimize recomputations during pre-render scene tree refresh.

Initialization parameters:

• Examples: iv::Image::attr_filename, iv::Prefsize::attr_prefsizeX, iv::Transform::attr_position
• Set from outside of element structure by user code.
• Dirty flag is cleared by element itself.

Synthesized parameters:

• Examples: iv::SlotChild::preferredSize
• Set by element itself during up-phase of first pass.
• Depends on synthesized parameters of children and/or own initialization parameters.
• Dirty flag is cleared by parent that uses the value to refresh its own synthesized parameters.

Inherited parameters:

• Examples: iv::SlotChild::size, iv::Elem::modelTransform, iv::Elem::scissor, iv::DividerSlot::attr_lowerOrder, iv::DividerSlot::attr_higherOrder, iv::TextSegment::location
• Set by parent in second pass.
• Depends on inherited, synthesized and initialization parameters of parent.
• Dirty flag is cleared by element itself which uses the value to set inherited parameters of its children or for rendering.