From 7ecc8790a49bb6e6fc0f789e2e62a40af56aa58c Mon Sep 17 00:00:00 2001
From: "sha..RD" <ShAdOwIsLoRd@gmail.com>
Date: Thu, 23 May 2013 01:58:41 +0000
Subject: [PATCH]  * Added overview / explanation on what Material.render()
 does

git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@10631 75d07b2b-3a1a-0410-a2c5-0572b91ccdca
---
 .../src/core/com/jme3/material/Material.java  | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)

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