NaviLibrary Overview
From NaviWiki
Contents |
What is NaviLibrary?
The question: wouldn't it be cool if you could make the GUI for your game with HTML?
NaviLibrary is the answer.
Utilizing Astral (our home-grown wrapper that allows us to embed Gecko, Mozilla Firefox's layout engine) we render a browser window to a texture-- NaviLibrary harnesses this functionality and provides an expressive interface to manipulate and display this dynamic content within Ogre3D.
A 'Navi' is an embedded browser window that you can interact with and display within your 3D scene-- you can either create it as an overlay on the viewport (like more traditional GUI windows) or as a pure material that you can apply to any mesh. To create a 'Navi' with NaviLibrary, the general outline is this:
- Design your page using HTML/CSS/Javascript.
- Instantiate the NaviManager.
- Load your page into a 'Navi' using the NaviManager.
- Hook-up events using Javascript and C++.
- Inject mouse input and update the NaviManager from your update loop.
Features
The beauty of NaviLibrary's approach is that the languages used (HTML, CSS, JS) are stable, widely-documented, and popular. The learning curve is shallow (as opposed to having to learn a proprietary syntax), development is short due to fast-prototyping (lots of WYSIWYG editors and instant testing using Mozilla Firefox & Firebug), and existing web design talent is easy to find (heck, my grandma designs her own MySpace layouts).
NaviLibrary is so much more than just your average GUI solution; because we are essentially embedding Gecko (think Firefox), almost everything you can do with Web 2.0 you can do inside an Ogre3D application. Yahoo's UI library, Dojo, MooTools, SVG, XUL, AJAX, Canvas, you name it. Thanks to Astral and Mozilla, NaviLibrary can do it (and you can too!).
Feature List
- Flexible Loading - You can load your pages/content from a URL, a local file, an Ogre Resource, or directly from a string of HTML.
- Javascript Evaluation - You can execute/evaluate arbitrary Javascript on any Navi! This is incredibly useful and makes manipulation of page content a breeze.
- Designed for Efficiency - Rendering content to a texture can take a toll on performance which is why Navis only render the 'dirty' sections of the browser window.
- The Web at your Fingertips - NaviLibrary opens up an entire new dimension to Ogre3D applications: the Internet. Use AJAX to fetch/send data without the need of an extra networking library, use Javascript to validate and extend the functionality of your Navis, use Canvas to create novel 2D visualizations, etc!
- Smart Input Handling - NaviManager handles hit-testing, mouse-input translation, and focusing of Navi-overlays for you, allowing you to use it more like a traditional GUI system.
- Alpha-Masking and Opacity - Navis can be masked using an alpha-mask and/or blended with a specific opacity.
- Intuitive Positioning - Positioning Navi-overlays on your viewport is easy using an expressive combo of relative and absolute specifiers.
- NaviMaterials - NaviMaterials are simply Ogre Materials that you can apply to any Ogre Entity of your choosing. They act just like Navi-overlays except that you must handle focusing and mouse-input injection directly. If you're looking to embed a Navi inside of another Ogre3D GUI library, you may derive a TexturePtr from this material and apply it to anything you like.
NaviData
NaviData is a message-passing system that you may use to communicate with your application from a page loaded into a Navi. It effectively allows you to serialize and deserialize groups of dynamic 'parameters' (either a String, Integer, or Float) that may be queried for value and name. NaviLibrary provides you with a Javascript library to embed in your pages if you choose to use the NaviData system.
Flash
Astral has limited support for Flash applications and cannot inject input into Flash objects nor automatically-update its texture. To see Flash content at all, you must override automatic updating (see Navi::setForceMaxUpdate). As a workaround for lack of input, you could manipulate the Flash object using Javascript.
XUL
XUL (pronounced 'Zool', rhymes with cool; XML User-interface Language) is a cross-platform language for describing user interfaces of applications. Obviously in the context of what NaviLibrary is, this is just way too cool. The syntax is very simple and straightforward and everything can be modified by CSS and Javascript. I highly recommend looking into XUL more if you're interested in learning new technology.
There are a few slight problems with XUL in NaviLibrary right now, specifically 'pop-up' menus and 'pop-up' color-pickers rendering outside the actual Render Window. Other than that, XUL works flawlessly, check out this example if you're using Firefox.
License
I am releasing Navi under the LGPL (GNU Lesser General Public License) with two stipulations:
- Any changes to NaviLibrary/Astral must be made available to me.
- If you use it in a project, [ajs15822@gmail.com tell me about it]! :)
