Nodes

Version 2 (coder, 27/03/2012 16:05)

1 1 admin
h1. Nodes
2 1 admin
3 1 admin
{{>toc}} 
4 1 admin
5 1 admin
h1. The Node Tree
6 1 admin
7 2 coder
libavg layout is based on nodes that represent things to display on the screen. These nodes are organized in a hierarchial structure - a tree. At the root of the tree is an @avg node@. This is very similar to html layout. In html, nodes like @div@ structure the page and nodes like @p@ or @img@ display content. libavg also has div nodes, but the content nodes are centered around graphics and include image, video, text and camera nodes as well as nodes that draw vector graphics. The non-div nodes are named leaves.
8 1 admin
9 2 coder
This tree (also called the _scene graph_) describes the logical and spatial layout of the nodes. It can be initialized either by using an xml screen layout file or by creating nodes in python. Parents of nodes influence the rendering of the child nodes. Again, this is very similar to html layout: div nodes structure the rendering area and determine where the children are rendered. This concept is similar to what is called the _DOM_ (Document Object Model) in xml and the _scene graph_ in 3D engines.
10 1 admin
11 1 admin
One very positive consequence of this design is that the system always knows what to display. The scene graph tells the libavg engine what media elements should be displayed and what their properties are. The user of the library does not need to specify what should to be displayed unless it changes. Besides making development easier, this design allows major speed optimizations in the rendering engine, because the engine has a global view of what needs to be done. The technical term for this behaviour is _retained-mode graphics_: The system retains the state of the display.
12 1 admin
13 1 admin
h1. Creating nodes
14 1 admin
15 1 admin
Besides specifying the libavg nodes to use in an xml file like in the Hello World example, nodes can be created in python. There are several ways to do this. The simplest one uses standard python constructors:
16 1 admin
17 1 admin
<pre><code class="python">
18 1 admin
newNode = avg.WordsNode(text='Hello libavg', pos=(10,30),
19 1 admin
        parent=player.getRootNode())
20 1 admin
</code></pre>
21 1 admin
22 1 admin
If you add this code to the minimal.py example, you should see the new text after you run the script. parent can be any div node. In this case, it's the root of the scenegraph.
23 1 admin
24 1 admin
You can also create nodes using xml:
25 1 admin
26 1 admin
_Alternative createNode:_
27 1 admin
28 1 admin
<pre><code class="python">
29 1 admin
newNode = player.createNode("""<words text="Hello libavg" pos="(10,30)"
30 1 admin
        />""")
31 1 admin
</code></pre>
32 1 admin
33 2 coder
Using the second syntax, whole node trees can be constructed with one call to @createNode@.