BGE: Allow access to original texture openGL Bind code/Id/Number
[blender.git] / doc / python_api / rst / bge_types / bge.types.KX_BlenderMaterial.rst
1 KX_BlenderMaterial(PyObjectPlus)
2 ================================
3
4 .. module:: bge.types
5
6 base class --- :class:`PyObjectPlus`
7
8 .. class:: KX_BlenderMaterial(PyObjectPlus)
9
10    This is the interface to materials in the game engine.
11
12    Materials define the render state to be applied to mesh objects.
13    
14    The example below shows a simple GLSL shader setup allowing to dynamically mix two texture channels
15    in a material. All materials of the object executing this script should have two textures using
16    separate UV maps in the two first texture channels.
17    
18    The code works for both Multitexture and GLSL rendering modes.
19
20    .. code-block:: python
21
22       from bge import logic
23       
24       vertex_shader = """
25       
26       void main(void)
27       {
28          // simple projection of the vertex position to view space
29          gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
30          // coordinate of the 1st texture channel
31          gl_TexCoord[0] = gl_MultiTexCoord0;
32          // coordinate of the 2nd texture channel
33          gl_TexCoord[1] = gl_MultiTexCoord1;
34       }
35       """
36       
37       fragment_shader ="""
38
39       uniform sampler2D texture_0;
40       uniform sampler2D texture_1;
41       uniform float factor;
42
43       void main(void)
44       {
45          vec4 color_0 = texture2D(texture_0, gl_TexCoord[0].st);
46          vec4 color_1 = texture2D(texture_1, gl_TexCoord[1].st);
47          gl_FragColor = mix(color_0, color_1, factor);
48       }
49       """
50
51       object = logic.getCurrentController().owner
52       
53       for mesh in object.meshes:
54           for material in mesh.materials:
55               shader = material.getShader()
56               if shader is not None:
57                   if not shader.isValid():
58                       shader.setSource(vertex_shader, fragment_shader, True)
59
60                   # get the first texture channel of the material
61                   shader.setSampler('texture_0', 0)
62                   # get the second texture channel of the material
63                   shader.setSampler('texture_1', 1)
64                   # pass another uniform to the shader
65                   shader.setUniform1f('factor', 0.3)
66
67    .. attribute:: shader
68
69       The material's shader.
70
71       :type: :class:`BL_Shader`
72
73    .. attribute:: blending
74
75       Ints used for pixel blending, (src, dst), matching the setBlending method.
76
77       :type: (integer, integer)
78
79    .. attribute:: material_index
80
81       The material's index.
82
83       :type: integer
84
85    .. method:: getShader()
86
87       Returns the material's shader.
88
89       :return: the material's shader
90       :rtype: :class:`BL_Shader`
91
92    .. method:: getTextureBindcode(textureslot)
93
94       Returns the material's texture OpenGL bind code/id/number/name.
95
96       :arg textureslot: Specifies the texture slot number
97       :type textureslot: integer
98       :return: the material's texture OpenGL bind code/id/number/name
99       :rtype: integer
100
101    .. attribute:: alpha
102
103       The material's alpha transparency.
104
105       :type: float between 0.0 and 1.0 inclusive
106
107    .. attribute:: hardness
108
109       How hard (sharp) the material's specular reflection is.
110
111       :type: integer between 1 and 511 inclusive
112
113    .. attribute:: emit
114
115       Amount of light to emit.
116
117       :type: float between 0.0 and 2.0 inclusive
118
119    .. attribute:: specularIntensity
120
121       How intense (bright) the material's specular reflection is.
122
123       :type: float between 0.0 and 1.0 inclusive
124
125    .. attribute:: diffuseIntensity
126
127       The material's amount of diffuse reflection.
128
129       :type: float between 0.0 and 1.0 inclusive
130
131    .. attribute:: specularColor
132
133       The material's specular color.
134
135       :type: :class:`mathutils.Color`
136
137    .. attribute:: diffuseColor
138
139       The material's diffuse color.
140
141       :type: :class:`mathutils.Color`
142
143    .. method:: setBlending(src, dest)
144
145       Set the pixel color arithmetic functions.
146
147       :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed, one of...
148       
149          * :data:`~bgl.GL_ZERO`
150          * :data:`~bgl.GL_ONE`
151          * :data:`~bgl.GL_SRC_COLOR`
152          * :data:`~bgl.GL_ONE_MINUS_SRC_COLOR`
153          * :data:`~bgl.GL_DST_COLOR`
154          * :data:`~bgl.GL_ONE_MINUS_DST_COLOR`
155          * :data:`~bgl.GL_SRC_ALPHA`
156          * :data:`~bgl.GL_ONE_MINUS_SRC_ALPHA`
157          * :data:`~bgl.GL_DST_ALPHA`
158          * :data:`~bgl.GL_ONE_MINUS_DST_ALPHA`
159          * :data:`~bgl.GL_SRC_ALPHA_SATURATE`
160       
161       :type src: int
162
163       :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed, one of...
164       
165          * :data:`~bgl.GL_ZERO`
166          * :data:`~bgl.GL_ONE`
167          * :data:`~bgl.GL_SRC_COLOR`
168          * :data:`~bgl.GL_ONE_MINUS_SRC_COLOR`
169          * :data:`~bgl.GL_DST_COLOR`
170          * :data:`~bgl.GL_ONE_MINUS_DST_COLOR`
171          * :data:`~bgl.GL_SRC_ALPHA`
172          * :data:`~bgl.GL_ONE_MINUS_SRC_ALPHA`
173          * :data:`~bgl.GL_DST_ALPHA`
174          * :data:`~bgl.GL_ONE_MINUS_DST_ALPHA`
175          * :data:`~bgl.GL_SRC_ALPHA_SATURATE`
176       
177       :type dest: int
178
179    .. method:: getMaterialIndex()
180
181       Returns the material's index.
182
183       :return: the material's index
184       :rtype: integer
185