Tech/LxEngine/User Manual
From Athile
It may contain inaccurate, incorrect information. Use at your own risk.
Contents |
Two Minute Overview
Note: this section is intended to reflect v1.0, which has not yet been reached.
The user code creates an single Engine object. The Engine provides common core services for logging, platform independence, debugging, and access to the other major system-level objects at run-time. The Engine can be configured to load up additional subsystems for services such as sound, physics, networking, scripting, etc.
The application then uses the Engine to open or create one or more Document objects. Each Document provides a Document Object Model (DOM) and an XML-like tree structure. The document can easily be manipulated using basic APIs or, more commonly, via the Javascript subsystem. Likewise, a CSS-like attribute inheritance subsystem is available from providing CSS-like behaviors for the Document objects.
Next, the application creates one or more View objects for each Document. These likewise are configured using a set of subsystem objects such as a rasterization subsystem (e.g. OGRE or LxCanvas), a user input subsystem (e.g. OIS or LxEngine's built-in system). Finally Controller objects can be attached to connect actual user actions (or network or script actions) to changes to the DOM and updates to the View.
These high-level subsystems are glued together using a simple string and scripting-based, reference-counted object system, which allows for simple configuration and customization. All the low-level, inner-loop code is using native C++ ensuring good performance. The goal is to get LxEngine as close to 'just working' from a simple configuration as is possible without complex build engineering to reconfigure compile options, etc. for each application being built.
The LxEngine SDK includes a host of necessary subsystems to create a complete application with a mix of custom, out-of-the-box, and hybrid Documents, Views, and Controllers. Likewise, it includes a fairly robust utility library of code to fill the gaps when writing custom components. The SDK itself has automated unit tests, benchmarks, and samples to demonstrate, develop, debug, and improve custom applications.
Overview
Document Object Model
LxCSS
LxQuery
A Javascript API designed to match the JQuery HTML manipulation library as closely as possible for LxEngine documents.
Middleware
LxEngine uses the OpenGL Mathematics (GLM) library, Boost, and (TBD). Functionality from these libraries can be used when linking to LxEngine.
Materials
Command-line Arguments
The Engine class provides a method Engine::parseCommandLine(argc, argv) method that is based on boost::program_options. This is an optional method (i.e. LxEngine will run correctly if it is not called) that is intended to provide a simple means for exposing application options on the command-line; but of course, if it does not meet the needs of the application, a custom command-line parser will work equally well.
Appendix A: How-To Cookbook
Document Object Model
How do I add support for a new Attribute?
The first question is: are you adding a new first-class attribute or a pseudo-attribute? See the LxCSS documentation to understand the distinction.
A pseudo-attribute can be added by implementing and registering a new __TBD__ class. This translates the user-specified values to first-class attribute values.
Adding a new first-class attribute depends on what the attributes purpose is. If it is a graphical attribute, then the graphics implementation for the Element::Component will likely need to be updated. If it is a physics attribute, then the physics Element::Component will likely need to be updated.
Graphics
How do I use a custom renderer rather than OGRE?
Write a new View implementation. The View will still no graphics services such as keyboard and mouse input.
In the case of an entirely new renderer, the lx libraries provide a lot of functionality to build the renderer from (e.g. quaternion and matrix classes, color classes, etc.).
