Docs: Manual - improve Instancing documentation

Author: paroj

Docs/src/manual.md

@@ -937,15 +937,24 @@ When implementing custom animable properties, you have to also implement a numbe
 
 @page Instancing Instancing
 
-Instancing significantly reduces the CPU overhead of submitting many separate draw calls and is a great technique for rendering trees, rocks, grass, RTS units and other groups of similar (but necessarily identical) objects.
+Modern graphics cards (GPUs) prefer to receive geometry in large
+batches. It is orders of magnitude faster to render 10 batches
+of 10,000 triangles than it is to render 10,000 batches of 10
+triangles, even though both result in the same number of on-screen
+triangles.
 
-OGRE supports a variety of techniques to speed up the rendering of many objects in the Scene.
+Therefore it is important when you are rendering a lot of geometry to
+batch things up into as few rendering calls as possible.
+
+%Ogre supports a variety of techniques to speed up the rendering of many objects in the Scene.
 
 <dl compact="compact">
 <dt>@ref Static-Geometry</dt>
 <dd>@copybrief Ogre::StaticGeometry </dd>
 <dt>@ref Instance-Manager</dt>
-<dd>Instancing is a way of batching up geometry into a much more efficient form, but with some limitations, and still be able to move & animate it.</dd>
+<dd>Choose from different algorithms to batch up geometry and still be able to move & animate it. Requires manual setup and the algorithms have some limitations.</dd>
+<dt>[Auto-Instancing](@ref Instancing-in-Vertex-Programs)</dt>
+<dd>You can advertise instancing in you shaders and Ogre will batch the draw calls for you. Does not support animation.This is less efficient than the Explicit Instance Manager but requires no code changes and can be used with the RTSS.</dd>
 </dl>
 
 @tableofcontents
@@ -956,7 +965,7 @@ OGRE supports a variety of techniques to speed up the rendering of many objects
 
 @see [Tutorial - Static Geometry](@ref tut_StaticGeom)
 
-# Instance Manager {#Instance-Manager}
+# Explicit Instance Manager {#Instance-Manager}
 Instancing is a rendering technique to draw multiple instances of the same mesh using just one render call. There are two kinds of instancing:
 
 @par Software

OgreMain/include/OgreInstanceBatchShader.h

@@ -39,8 +39,7 @@ namespace Ogre
     *  @{
     */
 
-    /** This is the same technique the old InstancedGeometry implementation used (with improvements).
-        Basically it creates a large vertex buffer with many repeating entities, and sends per instance
+    /** Basically it creates a large vertex buffer with many repeating entities, and sends per instance
         data through shader constants. Because SM 2.0 & 3.0 have up to 256 shader constant registers,
         this means there can be approx up to 84 instances per batch, assuming they're not skinned
         But using shader constants for other stuff (i.e. lighting) also affects negatively this number
@@ -50,7 +49,7 @@ namespace Ogre
         (SM 2.0 cards are required) and the same shader can be used for both skeletally animated
         normal entities and instanced entities without a single change required.
 
-        Unlike the old @c InstancedGeometry implementation, the developer doesn't need to worry about
+        The developer doesn't need to worry about
         reaching the 84 instances limit, the InstanceManager automatically takes care of splitting
         and creating new batches. But beware internally, this means less performance improvement.
         Another improvement is that vertex buffers are shared between batches, which significantly

OgreMain/include/OgreInstanceManager.h

@@ -41,7 +41,15 @@ namespace Ogre
     *  @{
     */
 
-    /** This is the main starting point for the new instancing system.
+    /** This is the main starting point for the manual instancing system.
+
+        Instancing allows to save both memory and draw calls. While
+        StaticGeometry stores 500 times the same object in a batch to display 500
+        objects, a hardware instancing implementation stores the object once,
+        and then re-uses the vertex data with different shader parameter.
+        You can move the batched objects independently of one another which
+        you cannot do with StaticGeometry.
+
         Each InstanceManager can control one technique and one mesh, but it can manage
         multiple materials at the same time.
         @ref SceneManager::createInstanceManager, which creates this InstanceManager. Each one

OgreMain/include/OgreStaticGeometry.h

@@ -42,24 +42,15 @@ namespace Ogre {
     /** \addtogroup Scene
     *  @{
     */
-    /** Pre-transforms and batches up meshes for efficient use as static
+    /** Pre-transforms and batches up meshes on the CPU for efficient use as static
         geometry in a scene.
 
-        Modern graphics cards (GPUs) prefer to receive geometry in large
-        batches. It is orders of magnitude faster to render 10 batches
-        of 10,000 triangles than it is to render 10,000 batches of 10 
-        triangles, even though both result in the same number of on-screen
-        triangles.
-    @par
-        Therefore it is important when you are rendering a lot of geometry to 
-        batch things up into as few rendering calls as possible. This
-        class allows you to build a batched object from a series of entities 
-        in order to benefit from this behaviour.
+        This class allows you to build a batched object from a series of entities.
         Batching has implications of it's own though:
-        @li Batched geometry cannot be subdivided; that means that the whole
+        - Batched geometry cannot be subdivided; that means that the whole
             group will be displayed, or none of it will. This obivously has
             culling issues.
-        @li A single world transform must apply to the entire batch. Therefore
+        - A single world transform must apply to the entire batch. Therefore
             once you have batched things, you can't move them around relative to
             each other. That's why this class is most useful when dealing with 
             static geometry (hence the name). In addition, geometry is 
@@ -68,18 +59,18 @@ namespace Ogre {
             space than the movable version (which re-uses the same geometry). 
             So you trade memory and flexibility of movement for pure speed when
             using this class.
-        @li A single material must apply for each batch. In fact this class 
+        - A single material must apply for each batch. In fact this class
             allows you to use multiple materials, but you should be aware that 
             internally this means that there is one batch per material. 
             Therefore you won't gain as much benefit from the batching if you 
             use many different materials; try to keep the number down.
-    @par
+
         In order to retain some sort of culling, this class will batch up 
         meshes in localised regions. The size and shape of these blocks is
         controlled by the SceneManager which constructs this object, since it
         makes sense to batch things up in the most appropriate way given the 
         existing partitioning of the scene. 
-    @par
+
         The LOD settings of both the Mesh and the Materials used in 
         constructing this static geometry will be respected. This means that 
         if you use meshes/materials which have LOD, batches in the distance 
@@ -91,15 +82,15 @@ namespace Ogre {
         not degraded). Be aware that using Mesh LOD in this class will 
         further increase the memory required. Only generated LOD
         is supported for meshes.
-    @par
+
         There are 2 ways you can add geometry to this class; you can add
         Entity objects directly with predetermined positions, scales and 
         orientations, or you can add an entire SceneNode and it's subtree, 
         including all the objects attached to it. Once you've added everything
         you need to, you have to call build() the fix the geometry in place. 
     @note
-        This class is not a replacement for world geometry (@ref 
-        Ogre::SceneManager::setWorldGeometry). The single most efficient way to 
+        This class is not a replacement for world geometry (@ref
+        Ogre::SceneManager::setWorldGeometry). The single most efficient way to
         render large amounts of static geometry is to use a SceneManager which 
         is specialised for dealing with that particular world structure. 
         However, this class does provide you with a good 'halfway house'
@@ -527,8 +518,8 @@ namespace Ogre {
 
     public:
         /**
-            You should not construct instances of this class directly; instead, call 
-            SceneManager::createStaticGeometry, which gives the SceneManager the 
+            You should not construct instances of this class directly; instead, call
+            SceneManager::createStaticGeometry, which gives the SceneManager the
             option of providing you with a specialised version of this class if it
             wishes, and also handles the memory management for you like other classes.
          */