diff options
author | Quentin Wenger <matpi@protonmail.ch> | 2015-06-17 23:41:25 +0300 |
---|---|---|
committer | Porteries Tristan <republicthunderbolt9@gmail.com> | 2015-06-17 23:43:29 +0300 |
commit | a62392dea7e6c99ad00dda8a2080d3944e9536cf (patch) | |
tree | 6572cbba54272ad3a003aaed8fef0abb4d2d37ab /doc | |
parent | 3ce4a58aa90d93d1d0f1ec5dcc63a482d1b1af78 (diff) |
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
Diffstat (limited to 'doc')
-rw-r--r-- | doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst | 119 | ||||
-rw-r--r-- | doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst | 250 |
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()) - |