urho3d/Docs/Urho3D.dox

namespace Urho3D
{

/**
\mainpage Urho3D - cross-platform 2D and 3D game engine

Urho3D (http://urho3d.github.io/) is a free lightweight, cross-platform 2D and 3D game engine implemented in C++ and released under the MIT license. It utilizes either Direct3D9 or OpenGL for rendering (%Shader %Model 2 or OpenGL 2.0 required as minimum.)

For getting started, see:

\ref Building "Building Urho3D" <br>
\ref Running "Running Urho3D player application" <br>
\ref UsingLibrary "Using Urho3D as external library" <br>
\ref Examples "Examples" <br>
\ref Structure "Overall structure" <br>
\ref Conventions "Conventions" <br>
\ref EditorInstructions "Editor instructions" <br>

For further reference, see:

\ref Containers "Container types" <br>
\ref ObjectTypes "Object types and factories" <br>
\ref Subsystems "Subsystems" <br>
\ref Events "Events" <br>
\ref MainLoop "Engine initialization and main loop" <br>
\ref SceneModel "Scene model" <br>
\ref Resources "Resources" <br>
\ref Scripting "Scripting" <br>
\ref LuaScripting "Lua scripting" <br>
\ref Rendering "Rendering" <br>
\ref Input "Input" <br>
\ref Audio "Audio" <br>
\ref Physics "Physics" <br>
\ref Navigation "Navigation" <br>
\ref UI "User interface" <br>
\ref Urho2D "Urho2D" <br>
\ref Serialization "Serialization" <br>
\ref Network "Networking" <br>
\ref Multithreading "Multithreading" <br>
\ref AttributeAnimation "Attribute animation" <br>
\ref Tools "Tools" <br>
\ref Unicode "Unicode support" <br>
\ref FileFormats "Custom file formats" <br>
\ref CodingConventions "Coding conventions" <br>
\ref ContributionChecklist "Contribution checklist" <br>
\ref ScriptAPI "Scripting API (generated)" <br>
\ref LuaScriptAPI "Lua scripting API (generated)" <br>
\ref EventList "Event list (generated)" <br>
\ref AttributeList "Attribute list (generated)" <br>

For Urho3D related links and projects, see \ref ExternalLinks "External links".

For credits, copyright and licensing information, see \ref Credits & \ref License.

For release history and major changes, see \ref History.

\page Credits Credits

Urho3D development, contributions and bugfixes by:
- Lasse &Ouml;&ouml;rni ([email protected], AgentC at GameDev.net)
- Wei Tjong Yao
- Aster Jian
- Colin Barrett
- Erik Beran
- Danny Boisvert
- Carlo Carollo
- Pete Chown
- Sebastian Delatorre (primitivewaste)
- Josh Engebretson
- Chris Friesen
- Alex Fuller
- Mika Heinonen
- Graham King
- Jason Kinzer
- Gunnar Kriik
- Ali K&auml;m&auml;r&auml;inen
- Pete Leigh
- Jonne Nauha
- Paul Noome
- David Palacios
- Alex Parlett
- Jordan Patterson
- Vladimir Pobedinsky
- Nick Royer
- Miika Santala
- Joshua Tippetts
- Daniel Wiberg
- Steven Zhang
- AGreatFish
- Firegorilla
- Magic.Lixin
- Mike3D
- OvermindDL1
- andmar1x
- amadeus_osa
- atship
- att
- celeron55
- hdunderscore
- mightyCelu
- nemerle
- ninjastone
- rasteron
- reattiva
- rifai
- skaiware
- szamq
- thebluefish

Urho3D is greatly inspired by OGRE (http://www.ogre3d.org/) and Horde3D (http://www.horde3d.org/). Additional inspiration & research used:

- Rectangle packing by Jukka Jyl&auml;nki (clb) (http://clb.demon.fi/projects/rectangle-bin-packing/)
- Tangent generation from Terathon (http://www.terathon.com/code/tangent.html)
- Fast, Minimum Storage Ray/Triangle Intersection by M&ouml;ller & Trumbore (http://www.graphics.cornell.edu/pubs/1997/MT97.pdf)
- Linear-Speed Vertex Cache Optimisation by Tom Forsyth (http://home.comcast.net/~tom_forsyth/papers/fast_vert_cache_opt.html)
- Software rasterization of triangles based on Chris Hecker's Perspective %Texture Mapping series in the Game Developer magazine (http://chrishecker.com/Miscellaneous_Technical_Articles)
- Networked Physics by Glenn Fiedler (http://gafferongames.com/game-physics/networked-physics/)
- Euler Angle Formulas by David Eberly (http://www.geometrictools.com/Documentation/EulerAngles.pdf)
- Red Black Trees by Julienne Walker (http://eternallyconfuzzled.com/tuts/datastructures/jsw_tut_rbtree.aspx)
- Comparison of several sorting algorithms by Juha Nieminen (http://warp.povusers.org/SortComparison/)

Urho3D uses the following third-party libraries:

- AngelScript 2.29.1 (http://www.angelcode.com/angelscript/)
- Box2D 2.3.0 (http://box2d.org/)
- Bullet 2.82 (http://www.bulletphysics.org/)
- Civetweb (http://sourceforge.net/projects/civetweb/)
- FreeType 2.5.0 (http://www.freetype.org/)
- GLEW 1.9.0 (http://glew.sourceforge.net/)
- jo_jpeg 1.52 (http://www.jonolick.com/uploads/7/9/2/1/7921194/jo_jpeg.cpp)
- kNet (https://github.com/juj/kNet)
- libcpuid 0.2.0 (http://libcpuid.sourceforge.net/)
- Lua 5.1 (http://www.lua.org)
- LuaJIT 2.0.3 (http://www.luajit.org)
- LZ4 (http://code.google.com/p/lz4/)
- MojoShader (http://icculus.org/mojoshader/)
- Open Asset Import Library (http://assimp.sourceforge.net/)
- rapidjson 0.11 (https://code.google.com/p/rapidjson/)
- pugixml 1.0 (http://pugixml.org/)
- Recast/Detour (http://code.google.com/p/recastnavigation/)
- SDL 2.0.3 (http://www.libsdl.org/)
- StanHull (http://codesuppository.blogspot.com/2006/03/john-ratcliffs-code-suppository-blog.html)
- stb_image 1.29 (http://nothings.org/)
- stb_vorbis 0.99996 (http://nothings.org/)
- tolua++ 1.0.93 (http://www.codenix.com/~tolua)

DXT / ETC1 / PVRTC decompression code based on the Squish library and the Oolong %Engine.<br>
Jack and mushroom models from the realXtend project. (http://www.realxtend.org)<br>
Ninja model and terrain, water, smoke, flare and status bar textures from OGRE.<br>
BlueHighway font from Larabie Fonts.<br>
Anonymous Pro font by Mark Simonson.<br>
NinjaSnowWar sounds by Veli-Pekka T&auml;til&auml;.


\page License License

Copyright (c) 2008-2014 the Urho3D project.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


\page History History

V1.32

- Finalized Urho2D functionality, including 2D physics using Box2D, sprite animation and tile maps
- Threaded background resource loading. Must be manually triggered via %ResourceCache or by loading a scene asynchronously
- Attribute and material shader parameter animation system
- Customizable onscreen joystick for mobile platforms. Used in examples
- Touch camera control in examples on mobile platforms
- Touch emulation by mouse
- Multi-touch UI drag support
- Consistent touch ID's across platforms
- Absolute, relative and wrap modes for the operating system mouse cursor
- Support for connecting & removing joysticks during runtime
- Negative light & light brightness multiplier support
- Transform spaces for %Node's translate, rotate & lookat functions
- Scrollable console
- Selectable console command interpreter (AngelScript, Lua, %FileSystem)
- Touch scroll in %ScrollView & %ListView
- %UI layout flex scale mode
- Custom sound streams from C++
- %LogicComponent C++ base class with virtual update functions similar to ScriptObject
- Signed distance field font support
- JSON data support
- Matrix types in %Variant & XML data
- Intermediate rendertarget refactoring: use viewport size to allow consistent UV addressing
- %ParticleEmitter refactoring: use %ParticleEffect resource for consistency with %ParticleEmitter2D and more optimal net replication
- Expose LZ4 compression functions
- Support various cube map layouts contained in a single image file
- Configurable Bullet physics stepping behavior. Can use elapsed time limiting, or a variable timestep to use less CPU
- Default construct math objects to zero / identity
- Mandatory registration for remote events. Check allowed event only when receiving
- Teapot & torus builtin objects
- FXAA 3.11 shader
- Triangle rendering in %DebugRenderer (more efficient than 3 lines)
- Material/texture quality and anisotropy as command line options and engine startup parameters
- %Spline math class, which the %SplinePath component uses
- %Console auto-show on error
- %DrawableProxy2D system for optimizing 2D sprite drawing
- Possibility to decouple %BorderImage border UV's from element size
- Editor & NinjaSnowWar resources split into subdirectories
- %UI hover start & end events
- %UI drag cancel by pressing ESC
- Allowed screen orientations can be controlled. Effective only on iOS
- Rendering sceneless renderpaths
- Define individual material passes as SM3-only
- Support for copying %ListView text to system clipboard
- Async system command execution
- Generic attribute access for Lua script objects
- Use Lua functions directly as event subscribers
- Touch gesture recording and load/save
- AssetImporter option to allow multiple import of identical meshes
- Automatically create a physics world component to scene when necessary
- GetSubimage function in the %Image class
- Possibility to clone existing components from another scene node
- Improve terrain rendering on mobile devices
- Refactoring of camera facing modes in %BillboardSet & %Text3D
- Additive alpha techniques for particle rendering
- Possibility to use %CustomGeometry component for physics triangle mesh collision
- Access to 2D node coordinates for convenience when using 2D graphics features
- Save embedded textures in AssetImporter
- Use best matching fullscreen resolution if no exact match
- Use SDL_iPhoneSetAnimationCallback instead of blocking main loop
- Allow fast partial terrain updates by modifying the heightmap image
- API for setting image pixels by integer colors
- Refactor to remove the separate ShortStringHash class
- Deep clone functionality in %Model resource
- %Zone can define a texture which is available to shaders. Not used by default
- Allow logging from outside the main thread
- %Log warnings for improper attempts to use events from outside main thread
- Improved %CustomGeometry dynamic updates
- ConvexCast function in %PhysicsWorld
- Screen to world space conversion functions in %Viewport class
- Allow sending client rotation to server in addition to position
- Allow accessing and modifying the engine's next timestep
- DeepEnabled mechanism for disabling node or UI element hierarchies and then restoring their own enabled state
- Allow to prevent closing a modal window with ESC
- Per-viewport control of whether debug geometry should render
- Optional interception of resource requests
- Readded optional slow & robust mode to %AreaAllocator
- Optionally disable %RigidBody mass update to allow fast adding of several %CollisionShape components to the same node
- Runtime synchronization of resource packages from server to client
- Disable multisample antialiasing momentarily during rendering. Used by default for UI & quad rendering
- Glyph offset support in %Font class
- %Font class internal refactoring
- Allow to create AngelScript script objects by specifying the interface it implements
- %Window position startup parameters
- Functions to get time since epoch & modify file's last modified time
- Optionally auto-disable child elements of a scroll view when touch scrolling
- Allocate views permanently per viewport to allow querying for drawables, lights etc. reliably
- Allow to specify material techniques/passes that should not be used on mobile devices
- Reduced default shadow mapping issues on mobile devices
- Minor rendering optimizations
- Build system: possibility to build Urho3D without networking or 2D graphics functionality
- Build system: improved generated scripting documentation
- Build system: improved support for IDE's in CMake scripts
- Build system: support up to Android NDK r10c and 64-bit ABIs
- Build system: numerous other improvements
- Editor: resource browser
- Editor: spawn window for random-generating objects
- Editor: allow either zoom or move from mouse wheel
- Editor: locate object by doubleclicking node in hierarchy
- Editor: take screenshots with F11, camera panning
- Editor: button in value edit fields that allows editing by mouse drag
- Updated SDL to 2.0.3.
- Updated AngelScript to 2.29.1
- Updated assimp
- Updated Recast/Detour
- Fix MinGW build issues
- Fix techniques referring to wrong shaders
- Fix %Node::LookAt() misbehaving in certain situations
- Fix resize event not reporting correct window size if window is maximized at start
- Fix %PhysicsWorld::GetRigidBodies() not using collision mask
- Fix zone misassignment issues
- Fix Lua not returning correctly typed object for %UIElement::GetChild() & %UIElement::GetParent()
- Fix uninitialized variables in 2D physics components
- Fix quad rendering not updating elapsed time uniform
- Fix forward rendering normal mapping issues by switching calculations back to world space
- Fix wrong logging level on Android
- Fix multiple subscribes to same event on Lua
- Fix missing %Octree update in headless mode
- Fix crash when using FreeType to access font kerning tables
- Fix ReadString() endless loop if the string does not end
- Fix shadow mapping on OS X systems with Intel GPU
- Fix manually positioned bones being serialized properly
- Fix file checksum calculation on Android
- Fix accelerometer input on Android when device is flipped 180 degrees
- Fix missing or misbehaving Lua bindings
- Fix crashes in physics collision handling when objects are removed during it
- Fix shader live reload if previous compile resulted in error
- Fix named manual textures not recreating their GPU resource after device loss
- Fix skeleton-only model not importing in AssetImporter
- Fix terrain raycast returning incorrect position/normal
- Fix animation keyframe timing in AssetImporter if start time is not 0
- Fix storing %Image resources to memory unnecessarily during cube/3D texture loading
- Fix to node transform dirtying mechanism and the TransformChanged() script function
- Fix returned documents directory not being writable on iOS
- Fix click to emptiness not closing a menu
- Fix %FileWatcher notifying when file was still being saved. By default delay notification 1 second
- Fix .txml import in the editor
- Fix erroneous raycast to triangles behind the ray
- Fix crash when multiple AnimatedModels exist in a node and the master model is destroyed
- Fix missing %Matrix4 * %Matrix3x4 operator in script
- Fix various compile warnings that leak to applications using Urho3D
- Fix %DebugHud update possibly being late one frame
- Fix various macros not being usable outside Urho3D namespace
- Fix erroneous layout with wordwrap text elements
- Fix debug geometry rendering on flipped OpenGL viewports
- Fix kNet debug mode assert with zero sized messages
- Fix not being able to stop and restart kNet server
- Fix %AreaAllocator operation
- Fix possible crash with parented rigidbodies
- Fix missing network delta update if only user variables in a %Node have been modified
- Fix to only search for June 2010 DirectX SDK, as earlier SDK's will fail
- Fix wrong search order of added resource paths
- Fix global anisotropic filtering on OpenGL
- Fix animation triggers not working if trigger is at animation end
- Fix CopyFramebuffer shader name not being used correctly on case-sensitive systems
- Fix %UI elements not receiving input when the window containing them is partially outside the screen to the left
- Fix occlusion rendering not working with counterclockwise triangles
- Fix material shader parameter animations going out of sync with other animations when the object using the material is not in view
- Fix CPU count functions on Android

V1.31

- Extensive build system improvements, especially for using Urho3D as a library in an external project.
- LuaJIT support.
- Improved Lua bindings, Lua coroutine support, automatic loading of compiled Lua scripts (.luc) if they exist.
- HDR rendering, 3D textures, height fog and several new post process shaders.
- %Shader refactoring. Need for XML shader descriptions & ShaderCompiler tool removed.
- Reflection / refraction rendering support.
- 2D drawable components: %StaticSprite2D, %AnimatedSprite2D, %ParticleEmitter2D.
- %ToolTip & %MessageBox %UI elements. %UI logic improvements.
- Optimized text rendering + dynamic population of font textures for improved batching.
- AngelScript DelayedExecute for free functions, and event handling for any script object, not just ScriptInstances
- Editor: added grid, toolbar, camera view presets, camera orbit, mouse wheel zoom, multiple viewports and orthographic camera.
- Borderless window mode, possibility to change application icon.
- SDL GameController support, raw key codes support.
- Optimized shadow rendering on mobile devices. Low quality mode avoids dependent texture reads.
- %HttpRequest class runs in a background thread to avoid blocking.
- Compressed package file support using the LZ4 library.
- Cone parameters in %SoundSource3D for directional attenuation.
- %Variant GetPtr() safety refactoring. Uses %WeakPtr's to store %RefCounted subclasses. Use GetVoidPtr() to store unsafe arbitrary pointers.
- Improved work queue completion events. Work items are now %RefCounted to allow persisting them as necessary.
- Allow to disable automatic execution of AngelScript & Lua from the engine console.
- Added shader variations, for example ambient occlusion texture and better emissive color support.
- Added examples.
- Update SDL to 2.0.1
- Update AngelScript to 2.28.1.
- Update FreeType to 2.5.0.
- Fix partial texture updates, both Direct3D9 & OpenGL.
- Fix long-standing audio click bug.
- Fix kinematic rigidbodies to apply impulses correctly to dynamic bodies.
- Plus many more improvements and bugfixes.

V1.3

- Lua scripting support.
- Optional build as a single external library, static or dynamic.
- Raspberry Pi support.
- 64-bit build support.
- HTTP client using the Civetweb library.
- Enhanced CMake build scripts. Android build also uses CMake. Use out-of-source build on platform that supports it.
- Rendering performance optimizations, optional %StaticModelGroup component for culling and lighting several objects as one unit.
- A set of sample applications implemented in C++, AngelScript and Lua.
- Automatic node/component handle member variable serialization for AngelScript script objects.
- New %UI theme.
- Shadow & stroke effects in %Text & %Text3D.
- Boolean shader uniforms.
- Quick menu in the editor.
- %Material editor and preview in the editor.
- Editable attributes for particle emitters.
- Components are grouped into categories in the editor.
- Update SDL to stable 2.0.0 release.
- Several other improvements and bugfixes.

V1.23

- %UI layout editing in the editor.
- Undo/redo in the editor.
- Recast/Detour library integration for navigation mesh generation and pathfinding.
- Open Asset Import Library update, enables FBX file support.
- "Is Enabled" attribute in scene nodes and components for an uniform mechanism to temporarily disable unneeded audiovisual, physics or logic objects.
- %Script object public variables editing and serialization.
- New components: %Text3D and %Sprite.
- %UI library functionality improvements.
- sRGB texture and framebuffer support.
- Switched to GLEW library for OpenGL extension handling.
- Vegetation and lightmapping example shaders.
- %Engine configuration through a parameter map.
- Lots of refactoring, code cleanup and bugfixes.

V1.22

- Configurable render path replaces hardcoded forward/prepass/deferred modes. Render path system also used for postprocessing now.
- Threaded task priorities; long-running tasks (more than one frame) can coexist with the time-critical tasks.
- Possibility to use also RGB normal maps.
- %CustomGeometry component, which allows geometry to be defined similarly to OpenGL immediate mode.
- Elapsed time shader parameter for material animation.
- Cubic environment mapping example shaders.
- Separate physics collision start & end events.
- Visual Studio 2012, Eclipse & Xcode build support.
- Many bugfixes, including iOS 6 orientation & shadow mapping bugfixes, and skinning on some Android devices.

V1.21

- Bugfixes and code cleanup.
- External window support (experimental.)
- %UI elements refactored to use attributes for serialization.
- %Animation state editing and animation trigger events.
- %Scene update time scale can be modified.
- Improved the delayed method call system.

V1.2

- Android and iOS support.
- %Decal rendering.
- %Terrain rendering.
- Joystick input support.
- Use SDL library for windowing and input on all platforms.
- KTX and PVR image loading (for ETC1 & PVRTC compressed textures.)
- Removed need for shader preprocessing; reorganized shaders to be more friendly to base custom shaders on.
- Inbuilt geometry shapes in the editor.

V1.16

- Switched to Bullet physics library.
- More physics constraint types.
- Rendering and networking performance optimizations.
- Use Squish library to implement software DXT decompression when not supported in hardware.

V1.15

- New deferred rendering pipeline.
- Unicode support.
- Live resource reloading in the editor (Windows only so far.)
- More accurate frame timing.
- Bugfixes to physics jittering and FBO performance issue on Linux.

V1.14

- %Object (partial scene) load/save.
- Post-processing.
- Switched to pugixml library, scene load/save optimizations.
- Bugfixes to rendertexture views and component attributes.

V1.13

- Task-based multithreading.
- Vertex lighting option.
- Forward and light pre-pass rendering pipelines.

V1.12

- Manipulator gizmo and multi-editing in the editor.
- Switched to forward rendering exclusively, which is optimized to do more work in the vertex shader.
- %Zone system refactoring. Objects check the zone they belong to for per-zone light masking, ambient light and fog settings.
- Scripting API fixes and improvements.

V1.11

- Bugfixes and performance optimizations.
- Added GraphicsTest example from V1.0 (now called TestSceneOld.)
- Added fallback mode, which is used if multiple render targets or hardware shadow maps are not available.

V1.1

- %Object and scene model refactoring.
- Automatic serialization of scene objects via attributes.
- Added OpenGL and cross-platform support.
- Switched to kNet library for networking.

V1.0

- Original release.

\page ExternalLinks External links

Related projects:

- Blender to Urho3D mesh exporter (https://github.com/reattiva/Urho3D-Blender)

- ParticleEditor2D for Urho3D (https://github.com/aster2013/ParticleEditor2D)

- Urho3D Launcher (https://github.com/Hgdavidy/Urho3D_Launcher_Tools)

- Urho3D libRocket Integration (https://github.com/realrunner/urho3d-librocket)

*/

}