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
This commit is contained in:
Quentin Wenger
parent
4fe9fe74ae
commit
c2420fee56
|
|
@ -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...
|
||||
: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
|
||||
|
||||
* 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 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()
|
||||
|
||||
|
|
|
|||
|
|
@ -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())
|
||||
|
||||
Loading…
Reference in New Issue