BGE: remove outdated doc of KX_PolygonMaterial, update doc of KX_BlenderMaterial

This patch suppresses the outdated KX_PolygonMaterial.rst documentation file and moves the example contained in it into KX_BlenderMaterial.rst.
The file KX_BlenderMaterial.rst receives some extra formatting changes (lists are not supported in methods arguments types).

Reviewers: kupoman, campbellbarton, lordloki, panzergame, moguri

Reviewed By: panzergame, moguri

Projects: #game_engine

Differential Revision: https://developer.blender.org/D1355

2 files changed, 88 insertions, 281 deletions

diff --git a/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst b/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst
index 0dfc7a10d13..80450526c9a 100644
--- a/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst
+++ b/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst
@@ -7,11 +7,66 @@ base class --- :class:`PyObjectPlus`
 
 .. class:: KX_BlenderMaterial(PyObjectPlus)
 
-   KX_BlenderMaterial
+   This is the interface to materials in the game engine.
+
+   Materials define the render state to be applied to mesh objects.
+   
+   The example below shows a simple GLSL shader setup allowing to dynamically mix two texture channels
+   in a material. All materials of the object executing this script should have two textures using
+   separate UV maps in the two first texture channels.
+   
+   The code works for both Multitexture and GLSL rendering modes.
+
+   .. code-block:: python
+
+      from bge import logic
+      
+      vertex_shader = """
+      
+      void main(void)
+      {
+         // simple projection of the vertex position to view space
+         gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
+         // coordinate of the 1st texture channel
+         gl_TexCoord[0] = gl_MultiTexCoord0;
+         // coordinate of the 2nd texture channel
+         gl_TexCoord[1] = gl_MultiTexCoord1;
+      }
+      """
+      
+      fragment_shader ="""
+
+      uniform sampler2D texture_0;
+      uniform sampler2D texture_1;
+      uniform float factor;
+
+      void main(void)
+      {
+         vec4 color_0 = texture2D(texture_0, gl_TexCoord[0].st);
+         vec4 color_1 = texture2D(texture_1, gl_TexCoord[1].st);
+         gl_FragColor = mix(color_0, color_1, factor);
+      }
+      """
+
+      object = logic.getCurrentController().owner
+      
+      for mesh in object.meshes:
+          for material in mesh.materials:
+              shader = material.getShader()
+              if shader is not None:
+                  if not shader.isValid():
+                      shader.setSource(vertex_shader, fragment_shader, True)
+
+                  # get the first texture channel of the material
+                  shader.setSampler('texture_0', 0)
+                  # get the second texture channel of the material
+                  shader.setSampler('texture_1', 1)
+                  # pass another uniform to the shader
+                  shader.setUniform1f('factor', 0.3)
 
    .. attribute:: shader
 
-      The materials shader.
+      The material's shader.
 
       :type: :class:`BL_Shader`
 
@@ -38,35 +93,37 @@ base class --- :class:`PyObjectPlus`
 
       Set the pixel color arithmetic functions.
 
-      :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed.
-      :type src: Value in...
-
-         * GL_ZERO,
-         * GL_ONE, 
-         * GL_SRC_COLOR, 
-         * GL_ONE_MINUS_SRC_COLOR, 
-         * GL_DST_COLOR, 
-         * GL_ONE_MINUS_DST_COLOR, 
-         * GL_SRC_ALPHA, 
-         * GL_ONE_MINUS_SRC_ALPHA, 
-         * GL_DST_ALPHA, 
-         * GL_ONE_MINUS_DST_ALPHA, 
-         * GL_SRC_ALPHA_SATURATE
-
-      :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed.
-      :type dest: Value in...
-
-         * GL_ZERO
-         * GL_ONE
-         * GL_SRC_COLOR
-         * GL_ONE_MINUS_SRC_COLOR
-         * GL_DST_COLOR
-         * GL_ONE_MINUS_DST_COLOR
-         * GL_SRC_ALPHA
-         * GL_ONE_MINUS_SRC_ALPHA
-         * GL_DST_ALPHA
-         * GL_ONE_MINUS_DST_ALPHA
-         * GL_SRC_ALPHA_SATURATE
+      :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed, one of...
+      
+         * :data:`~bgl.GL_ZERO`
+         * :data:`~bgl.GL_ONE`
+         * :data:`~bgl.GL_SRC_COLOR`
+         * :data:`~bgl.GL_ONE_MINUS_SRC_COLOR`
+         * :data:`~bgl.GL_DST_COLOR`
+         * :data:`~bgl.GL_ONE_MINUS_DST_COLOR`
+         * :data:`~bgl.GL_SRC_ALPHA`
+         * :data:`~bgl.GL_ONE_MINUS_SRC_ALPHA`
+         * :data:`~bgl.GL_DST_ALPHA`
+         * :data:`~bgl.GL_ONE_MINUS_DST_ALPHA`
+         * :data:`~bgl.GL_SRC_ALPHA_SATURATE`
+      
+      :type src: int
+
+      :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed, one of...
+      
+         * :data:`~bgl.GL_ZERO`
+         * :data:`~bgl.GL_ONE`
+         * :data:`~bgl.GL_SRC_COLOR`
+         * :data:`~bgl.GL_ONE_MINUS_SRC_COLOR`
+         * :data:`~bgl.GL_DST_COLOR`
+         * :data:`~bgl.GL_ONE_MINUS_DST_COLOR`
+         * :data:`~bgl.GL_SRC_ALPHA`
+         * :data:`~bgl.GL_ONE_MINUS_SRC_ALPHA`
+         * :data:`~bgl.GL_DST_ALPHA`
+         * :data:`~bgl.GL_ONE_MINUS_DST_ALPHA`
+         * :data:`~bgl.GL_SRC_ALPHA_SATURATE`
+      
+      :type dest: int
 
    .. method:: getMaterialIndex()
 
diff --git a/doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst b/doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst
deleted file mode 100644
index 3421e194d77..00000000000
--- a/doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst
+++ /dev/null
@@ -1,250 +0,0 @@
-KX_PolygonMaterial(PyObjectPlus)
-================================
-
-.. module:: bge.types
-
-base class --- :class:`PyObjectPlus`
-
-.. class:: KX_PolygonMaterial(PyObjectPlus)
-
-   This is the interface to materials in the game engine.
-
-   Materials define the render state to be applied to mesh objects.
-
-   .. warning::
-
-      Some of the methods/variables are CObjects.  If you mix these up, you will crash blender.
-
-   .. code-block:: python
-
-      from bge import logic
-      
-      vertex_shader = """
-      
-      void main(void)
-      {
-         // original vertex position, no changes
-         gl_Position = ftransform();
-         // coordinate of the 1st texture channel
-         gl_TexCoord[0] = gl_MultiTexCoord0;
-         // coordinate of the 2nd texture channel
-         gl_TexCoord[1] = gl_MultiTexCoord1;
-      }
-      """
-      
-      fragment_shader ="""
-
-      uniform sampler2D color_0;
-      uniform sampler2D color_1;
-      uniform float factor;
-
-      void main(void)
-      {
-         vec4 color_0 = texture2D(color_0, gl_TexCoord[0].st);
-         vec4 color_1 = texture2D(color_1, gl_TexCoord[1].st);
-         gl_FragColor = mix(color_0, color_1, factor);
-      }
-      """
-
-      object = logic.getCurrentController().owner
-      object = cont.owner
-      for mesh in object.meshes:
-          for material in mesh.materials:
-              shader = material.getShader()
-              if shader != None:
-                  if not shader.isValid():
-                      shader.setSource(vertex_shader, fragment_shader, True)
-
-                  # get the first texture channel of the material
-                  shader.setSampler('color_0', 0)
-                  # get the second texture channel of the material
-                  shader.setSampler('color_1', 1)
-                  # pass another uniform to the shader
-                  shader.setUniform1f('factor', 0.3)
-
-
-   .. attribute:: texture
-
-      Texture name.
-
-      :type: string (read-only)
-
-   .. attribute:: gl_texture
-
-      OpenGL texture handle (eg for glBindTexture(GL_TEXTURE_2D, gl_texture).
-
-      :type: integer (read-only)
-
-   .. attribute:: material
-
-      Material name.
-
-      :type: string (read-only)
-
-   .. attribute:: tface
-
-      Texture face properties.
-
-      :type: CObject (read-only)
-
-   .. attribute:: tile
-
-      Texture is tiling.
-
-      :type: boolean
-
-   .. attribute:: tilexrep
-
-      Number of tile repetitions in x direction.
-
-      :type: integer
-
-   .. attribute:: tileyrep
-
-      Number of tile repetitions in y direction.
-
-      :type: integer
-
-   .. attribute:: drawingmode
-
-      Drawing mode for the material.
-      - 2  (drawingmode & 4)     Textured
-      - 4  (drawingmode & 16)    Light
-      - 14 (drawingmode & 16384) 3d Polygon Text.
-
-      :type: bitfield
-
-   .. attribute:: transparent
-
-      This material is transparent. All meshes with this
-      material will be rendered after non transparent meshes from back
-      to front.
-
-      :type: boolean
-
-   .. attribute:: zsort
-
-      Transparent polygons in meshes with this material will be sorted back to
-      front before rendering.
-      Non-Transparent polygons will be sorted front to back before rendering.
-
-      :type: boolean
-
-   .. attribute:: diffuse
-
-      The diffuse color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0].
-
-      :type: list [r, g, b]
-
-   .. attribute:: specular
-
-      The specular color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0].
-
-      :type: list [r, g, b]
-
-   .. attribute:: shininess
-
-      The shininess (specular exponent) of the material. 0.0 <= shininess <= 128.0.
-
-      :type: float
-
-   .. attribute:: specularity
-
-      The amount of specular of the material. 0.0 <= specularity <= 1.0.
-
-      :type: float
-
-   .. method:: updateTexture(tface, rasty)
-
-      Updates a realtime animation.
-
-      :arg tface: Texture face (eg mat.tface)
-      :type tface: CObject
-      :arg rasty: Rasterizer
-      :type rasty: CObject
-
-   .. method:: setTexture(tface)
-
-      Sets texture render state.
-
-      :arg tface: Texture face
-      :type tface: CObject
-
-      .. code-block:: python
-
-         mat.setTexture(mat.tface)
-         
-   .. method:: activate(rasty, cachingInfo)
-
-      Sets material parameters for this object for rendering.
-
-      Material Parameters set:
-
-      #. Texture
-      #. Backface culling
-      #. Line drawing
-      #. Specular Colour
-      #. Shininess
-      #. Diffuse Colour
-      #. Polygon Offset.
-
-      :arg rasty: Rasterizer instance.
-      :type rasty: CObject
-      :arg cachingInfo: Material cache instance.
-      :type cachingInfo: CObject
-
-   .. method:: setCustomMaterial(material)
-
-      Sets the material state setup object.
-
-      Using this method, you can extend or completely replace the gameengine material
-      to do your own advanced multipass effects.
-
-      Use this method to register your material class.  Instead of the normal material, 
-      your class's activate method will be called just before rendering the mesh.
-      This should setup the texture, material, and any other state you would like.
-      It should return True to render the mesh, or False if you are finished.  You should
-      clean up any state Blender does not set before returning False.
-
-      Activate Method Definition:
-
-      .. code-block:: python
-      
-         def activate(self, rasty, cachingInfo, material):
-
-      :arg material: The material object.
-      :type material: instance
-
-      .. code-block:: python
-
-         class PyMaterial:
-           def __init__(self):
-             self.pass_no = -1
-           
-           def activate(self, rasty, cachingInfo, material):
-             # Activate the material here.
-             #
-             # The activate method will be called until it returns False.
-             # Every time the activate method returns True the mesh will
-             # be rendered.
-             #
-             # rasty is a CObject for passing to material.updateTexture() 
-             #       and material.activate()
-             # cachingInfo is a CObject for passing to material.activate()
-             # material is the KX_PolygonMaterial instance this material
-             #          was added to
-             
-             # default material properties:
-             self.pass_no += 1
-             if self.pass_no == 0:
-               material.activate(rasty, cachingInfo)
-               # Return True to do this pass
-               return True
-             
-             # clean up and return False to finish.
-             self.pass_no = -1
-             return False
-         
-         # Create a new Python Material and pass it to the renderer.
-         mat.setCustomMaterial(PyMaterial())
-