- The Life cycle
- Inside a Paper3D context
Paper3D is a cross platform rendering engine. It is built upon a fundamental library, named Tech, which is also a Future Interface’s product. Tech is shared by many Future Interface engine products, like Paper3D and Panel3D. It provides many low level utilities and platform encapsulation, and leaves the upper engine module focusing on the specific functionality. The following figure depicts the high-level module view of the Paper3D engine.
Tech. The platform module takes charge of wrapping up the details of window management, the input, and EGL surface management and providing a unified interface to the underneath layers so that these layers don’t need to worry about platform specific stuff. In the ver0.9 pre, platform module has included the support of Android and win32. The support of iOS is planned in ver0.91 pre. To implement a new platform support module for Paper3D, TBD is the best reference. Next is paper3d layer, it contains particular functionality of Paper3D engine, like animation, scene graph and so on. We will cover the detail in section 2.Modules. foundation is a second major module of Tech. It contains a variant of utilities, the lifecycle management and wrappers to system calls on different platforms. Again, it will be detailed in section 2.Modules. Paper3D relies on OpenGL ES 2.0 and C runtime library to carry out its functionality. On Win32 platform, we use OpenGL ES 2.0 simulator from Imagination.
Paper3D contains four major modules, from top to bottom, platform, paper3d, foundation and 3rd-party library. They are wired up in a layer-like structure. The top layer is dependent on the bottom one but not the other way around. That means a top layer can call functions in the bottom layer but bottom layer cannot. For example, paper3d layer can use math functions in the foundation layer, but foundation layer doesn’t ever call function in the paper3d layer.
The topmost layer platform is essentially a wrapper of the window system. It has three modules, window, input and EGL surface. Each of these modules encapsulates the different usage of system and provides a uniform interface and data format to the layers underneath. Window module wraps up the creating a window, the main loop of the window, destroying a window and specific window events, e.g., window resizing. Each change to the window will notify the corresponding paper3d application context the by the window module. For the lifecycle of a paper3d application, one can refer to Section lifecycle, The EGL surface module namely takes charge to creating a EGL surface, initializing the OpenGL context, destroying surface and context, and swap buffers at every frame. It doesn’t have any linkage to the bottom layers. The input module translates the system input event to the paper3d one. For example, the mouse event in win32 platform is translated to a touch event in paper3d.
paper3d layer contains all the specific functionality of paper3d. It has the scene graph, the animation, the particle system, resource management and a few others. Each module tackles the functionality that their names explain.
The foundation layer has two types of modules. One is context-related module (in dark purple) and the other is helper functions or classes (in light purple). The first type of modules serve the context directly. For example, the event module manages the event queue in an application context and lists all event types supported by paper3d. Runtime module is a core module in paper3d architecture. It is the interface of paper3d layer to the platform layer and drives the operation of an the paper3d application. In Section XXX, we will describe more about it. The second type of module are utility functions or classes. They are either system function wrappers or algorithm collections to be called by other modules at the top. For example, math module provides all kinds of vector math in C++ and a few other common math functions in graphics.
paper3d adopts four 3rd-party libraries, libpng, libz, tinyxml and inih. libpng and libz are for PNG image loading and saving. The tinyxml is a XML parser and inih is INI file parser.
The Life cycle
Paper3D has embedded the main function of each OS into the engine. For example, the main function on win32 platform can be found at platform\win32\main.cpp. The main function initiates a paper3d application, enters a main event loop and destroy the application when the event looping breaks. The whole life cycle of Paper3D is depicted in above figure.
As we already said, after operating system boots up the application and enters the main function, the platform layer of Paper3D takes over. It first creates a window and an EGL surface. Either of these two steps fails, the application will stop. Otherwise, it calls the foundation layer to create a PActivity instance and a PContext instance using parameters given by user. Then platform enters the main loop. At each iteration of the main loop, the input and other events including resume, pause and change to the window surface from operating system will translated into native events of paper3d and passed to PContext instance, and also PContext instance will call its update routing to update the context status and do the rendering afterwards. When the mainloop breaks by either the execution error and quit event issued by PContext instance, platform layer will first call foundation layer to destroy PContext and PActivity instance and then it does its own cleanup and return the control to the operating system.
Inside a Paper3D context
Paper3D assigns a PContext instance to each window (or view in Android), or say each PContext is associated with one EGL context. One Paper3D application may contain more than one PContext instances and all these PContext instances are managed by PActivity instance which is unique in one application.
Each PContext instance contains a few module instances. All these module class are inheriting PModule which has 5 virtual interface functions.
At specific event, e.g., update, PContext will iterate all these modules one by one and call their update function if any. The order of module traversal is determined by the module’s index in the module array. initialize, update and pause iterate modules in forward direction, while uninitialize and resume iterate modules in the reversed direction.
- PSceneManager: organizes the scene graph, updates the each node of scene graph at every frame, and does the rendering.
- PEffectManager: manages the full screen posteffects and execute these effects
- PAnimationManager: manages all animations in the scene, play and stop animations
- PResourceManager: load and destroy mesh, texture, material and animation resource in the scene.
- PEventManager: the event queue of all events in the context.
- PGestureManager: decipher the touch events into gesture events.