* Added overview / explanation on what Material.render() does

git-svn-id: http://jmonkeyengine.googlecode.com/svn/trunk@10631 75d07b2b-3a1a-0410-a2c5-0572b91ccdca

diff --git a/engine/src/core/com/jme3/material/Material.java b/engine/src/core/com/jme3/material/Material.java
index cea6059..b9830d9 100644 (file)
--- a/engine/src/core/com/jme3/material/Material.java
+++ b/engine/src/core/com/jme3/material/Material.java
@@ -42,12 +42,14 @@ import com.jme3.material.TechniqueDef.LightMode;
 import com.jme3.material.TechniqueDef.ShadowMode;\r
 import com.jme3.math.*;\r
 import com.jme3.renderer.Caps;\r
+import com.jme3.renderer.GL1Renderer;\r
 import com.jme3.renderer.RenderManager;\r
 import com.jme3.renderer.Renderer;\r
 import com.jme3.renderer.queue.RenderQueue.Bucket;\r
 import com.jme3.scene.Geometry;\r
 import com.jme3.shader.Shader;\r
 import com.jme3.shader.Uniform;\r
+import com.jme3.shader.UniformBindingManager;\r
 import com.jme3.shader.VarType;\r
 import com.jme3.texture.Texture;\r
 import com.jme3.util.ListMap;\r
@@ -995,6 +997,56 @@ public class Material implements CloneableSmartAsset, Cloneable, Savable {
     /**\r
      * Called by {@link RenderManager} to render the geometry by\r
      * using this material.\r
+     * <p>\r
+     * The material is rendered as follows:\r
+     * <ul>\r
+     * <li>Determine which technique to use to render the material - \r
+     * either what the user selected via \r
+     * {@link #selectTechnique(java.lang.String, com.jme3.renderer.RenderManager) \r
+     * Material.selectTechnique()}, \r
+     * or the first default technique that the renderer supports \r
+     * (based on the technique's {@link TechniqueDef#getRequiredCaps() requested rendering capabilities})<ul>\r
+     * <li>If the technique has been changed since the last frame, then it is notified via \r
+     * {@link Technique#makeCurrent(com.jme3.asset.AssetManager, boolean, java.util.EnumSet) \r
+     * Technique.makeCurrent()}. \r
+     * If the technique wants to use a shader to render the model, it should load it at this part - \r
+     * the shader should have all the proper defines as declared in the technique definition, \r
+     * including those that are bound to material parameters. \r
+     * The technique can re-use the shader from the last frame if \r
+     * no changes to the defines occurred.</li></ul>\r
+     * <li>Set the {@link RenderState} to use for rendering. The render states are \r
+     * applied in this order (later RenderStates override earlier RenderStates):<ol>\r
+     * <li>{@link TechniqueDef#getRenderState() Technique Definition's RenderState}\r
+     * - i.e. specific renderstate that is required for the shader.</li>\r
+     * <li>{@link #getAdditionalRenderState() Material Instance Additional RenderState}\r
+     * - i.e. ad-hoc renderstate set per model</li>\r
+     * <li>{@link RenderManager#getForcedRenderState() RenderManager's Forced RenderState}\r
+     * - i.e. renderstate requested by a {@link com.jme3.post.SceneProcessor} or\r
+     * post-processing filter.</li></ol>\r
+     * <li>If the technique {@link TechniqueDef#isUsingShaders() uses a shader}, then the uniforms of the shader must be updated.<ul>\r
+     * <li>Uniforms bound to material parameters are updated based on the current material parameter values.</li>\r
+     * <li>Uniforms bound to world parameters are updated from the RenderManager.\r
+     * Internally {@link UniformBindingManager} is used for this task.</li>\r
+     * <li>Uniforms bound to textures will cause the texture to be uploaded as necessary. \r
+     * The uniform is set to the texture unit where the texture is bound.</li></ul>\r
+     * <li>If the technique uses a shader, the model is then rendered according \r
+     * to the lighting mode specified on the technique definition.<ul>\r
+     * <li>{@link LightMode#SinglePass single pass light mode} fills the shader's light uniform arrays \r
+     * with the first 4 lights and renders the model once.</li>\r
+     * <li>{@link LightMode#MultiPass multi pass light mode} light mode renders the model multiple times, \r
+     * for the first light it is rendered opaque, on subsequent lights it is \r
+     * rendered with {@link BlendMode#AlphaAdditive alpha-additive} blending and depth writing disabled.</li>\r
+     * </ul>\r
+     * <li>For techniques that do not use shaders, \r
+     * fixed function OpenGL is used to render the model (see {@link GL1Renderer} interface):<ul>\r
+     * <li>OpenGL state ({@link FixedFuncBinding}) that is bound to material parameters is updated. </li>\r
+     * <li>The texture set on the material is uploaded and bound. \r
+     * Currently only 1 texture is supported for fixed function techniques.</li>\r
+     * <li>If the technique uses lighting, then OpenGL lighting state is updated \r
+     * based on the light list on the geometry, otherwise OpenGL lighting is disabled.</li>\r
+     * <li>The mesh is uploaded and rendered.</li>\r
+     * </ul>\r
+     * </ul>\r
      *\r
      * @param geom The geometry to render\r
      * @param rm The render manager requesting the rendering\r