Home       Trees       Index       Help   

Blender GameEngine

Module KX_PolygonMaterial :: Class KX_PolygonMaterial
[frames | no frames]

Class KX_PolygonMaterial

This is the interface to materials in Blender.

Materials define the render state to be applied to mesh objects.

Example:

This example does perpixel normal mapping. It needs a textured mesh, and a normal map in the first active texture slot.

vertex.vs: 
       uniform mat4 MVI; // Inverse ModelView Matrix
       
       attribute vec4 vertex_tangent;
       
       varying vec3 lightvec;
       varying vec3 viewvec;
       
       void main ()
       {
               // Transform vertex to clip space
               gl_Position = gl_ModelViewProjectionMatrix*gl_Vertex;   
               
               // Create Tangent Space Matrix
               mat4 tangent;
               tangent[1].xyz = cross(vertex_tangent.xyz, gl_Normal.xyz)*vertex_tangent.w;
               tangent[0].xyz = vertex_tangent.xyz;
               tangent[2].xyz = gl_Normal;
               tangent[3] = -gl_Vertex;
               
               vec4 lightpos = MVI*gl_LightSource[0].position;
               lightvec = (lightpos*tangent).xyz;
               
               viewvec = (MVI[3]*tangent).xyz;
               
               // UV Coordinates
               gl_TexCoord[0] = gl_MultiTexCoord0;
               // Vertex colours
               gl_FrontColor = gl_Color;
       }
fragment.fs: 
       uniform sampler2D colourmap;
       uniform sampler2D normap;
       
       varying vec3 lightvec;
       varying vec3 viewvec;
       
       void main()
       {
               // Tangent space light vector
               vec3 lv = normalize(lightvec);
       
               // Tangent space view vector
               vec3 vv = normalize(viewvec);
       
               // Lookup normal
               // Scale & bias normal
               // Normalise normal
               vec3 normal = normalize(2.0*texture2D(normap, gl_TexCoord[0]).xyz - 1.0);
       
               // Compute diffuse lighting
               float diffuse = dot(normal, lv);
               vec3 refl = normalize(2.0*diffuse*normal - lv);
       
               // Compute specular lighting
               float spec = pow(max(dot(refl, vv), 0.0), gl_FrontMaterial.shininess);
       
               // Lookup colour map
               vec4 colour = texture2D(colourmap, gl_TexCoord[0]) * gl_LightSource[0].diffuse * diffuse;
       
               // light colour map
               gl_FragColor = spec * gl_FrontMaterial.specular * gl_LightSource[0].specular + colour;
               // Pass alpha
               gl_FragColor.a = colour.a;
       }
LoadShaders.py: 
       import GameLogic
       
       mats = GameLogic.getCurrentController().getOwner().getMesh().materials
       shaders = [(mats[0].VERTEX_SHADER, "vertex.vs"),
                  (mats[0].FRAGMENT_SHADER, "fragment.fs")]
       
       for mat in mats:
               for shader in shaders:
                       mat.loadShader(shader[0], shader[1], shader[1])
               
               # Set Textures...
               mat.setUniform("colourmap", 0)
               mat.setUniform("normap", 1)
               # Set MV inverse matrix
               mat.genUniform("MVI", 2)
               # Bind tangent space
               mat.bindAttribute("vertex_tangent", 1)

Bug: All attributes are read only.

Method Summary
  bindAttribute(name, location)
Binds an attribute location to a name.
  genUniform(name, value)
Generates a shader uniform parameter.
  loadProgram(source, name)
Loads an assembly program into the material.
  loadShader(shadertype, source, name)
Loads a GLSL shader into the material.
  setCustomMaterial(material)
Sets the material state setup object.
  setUniform(name, value, transpose)
Sets a shader uniform parameter.

Instance Variable Summary
list [r, g, b, a] diffuse: The diffuse colour of the material.
bitfield drawingmode: Drawing mode for the material.
bitfield. lightlayer: Light layers this material affects.
  linearsubsurf: True if the subdivision method does not alter the shape of the mesh.
string material: Material name
float shininess: The shininess (specular exponent) of the material.
boolean smooth: See "Set Smooth/Set Solid" If smooth is false (Solid) and the mesh has armatures, the face normals will be recalculated.
list [r, g, b, a] specular: The specular colour of the material.
float specularity: The amount of specular of the material.
integer subsurf: The amount of mesh smoothing to apply.
string texture: Texture name
boolean tile: Texture is tiling
integer tilexrep: Number of tile repetitions in x direction.
integer tileyrep: Number of tile repetitions in y direction.
boolean transparent: This material is transparent.
boolean triangle: Mesh data with this material is triangles.
boolean zsort: Transparent polygons in meshes with this material will be sorted back to front before rendering.
    Constants
  VERTEX_SHADER: Vertex shader (see loadShader)
  FRAGMENT_SHADER: Fragment shader (see loadShader)

Method Details

bindAttribute(name, location)

Binds an attribute location to a name.

Available attributes:
  1. Vertex Tangent. Bitangent = (normal X tangent)*tangent.w
Parameters:
name - attribute to bind.
           (type=string)
location - attribute location.
           (type=integer)

genUniform(name, value)

Generates a shader uniform parameter.
  1. Model-View Matrix
  2. Model-View Matrix Transposed
  3. Inverse Model-View Matrix
  4. Inverse Model-View Transposed
  5. Model Matrix
  6. Model Matrix Transposed
  7. Inverse Model Matrix
  8. Inverse Model Matrix Transposed
  9. View Matrix
  10. View Matrix Transposed
  11. Inverse View Matrix
  12. Inverse View Matrix Transposed
  13. (unsigned int) Number of Lights (Unimplemented)
  14. (unsigned int) Current eye in stereo mode. (0 = Left, 1 = Right)
Parameters:
name - The name of the uniform to load.
           (type=string)
value - The value to load into the uniform. (See list above)
           (type=integer)

Bug: These constants should be given names.

loadProgram(source, name)

Loads an assembly program into the material.

The type of program will be deduced from the source header:
  1. !!ARBvp1.0 Vertex Program (GL_ARB_vertex_program)
  2. !!ARBfp1.0 Fragment Program (GL_ARB_fragment_program)
Parameters:
source - The program to load. Can be either the source itself, or the name of a text space.
           (type=string)
name - (Optional) The name of the program. The name is printed to the console for debugging.
           (type=string)

loadShader(shadertype, source, name)

Loads a GLSL shader into the material.
Parameters:
shadertype - VERTEX_SHADER or FRAGMENT_SHADER
source - The shader to load. Can be either the source itself, or the name of a text space.
           (type=string)
name - (Optional) The name of the shader. The name is printed to the console for debugging.
           (type=string)

setCustomMaterial(material)

Sets the material state setup object.

Example: 
       class PyMaterial:
               def Activate(self):
                       # Activate is called first.
                       # It returns True if this material is multipass
                       return False
               def ActivateNextPass(self, p):
                       # Called before each pass.
                       # Returns True if this pass should be rendered.
                       return p == 0 # Single pass
               def ActivateMeshSlot(self):
                       # Called for each mesh to be rendered.
                       pass
               def Deactivate(self):
                       # Called to finish rendering.
                       pass
       
       # Create a new Python Material and pass it to the renderer.
       mat.setCustomMaterial(PyMaterial())
Parameters:
material - The material object.
           (type=instance)

setUniform(name, value, transpose=0)

Sets a shader uniform parameter.

You can pass parameters to your shader with this method.
Parameters:
name - The name of the uniform to load.
           (type=string)
value - The value of the uniform to load.
           (type=integer, float, vec2, vec3, vec4, mat3, mat4)
transpose - (Optional) For matrix types, whether to transpose the matrix on load.
           (type=boolean)

Instance Variable Details

VERTEX_SHADER

Vertex shader (see loadShader)

FRAGMENT_SHADER

Fragment shader (see loadShader)

diffuse

The diffuse colour of the material. black = [0.0, 0.0, 0.0, 1.0] white = [1.0, 1.0, 1.0, 1.0]
Type:
list [r, g, b, a]

drawingmode

Drawing mode for the material.
  • 2 (drawingmode & 4) Textured
  • 4 (drawingmode & 16) Light
  • 14 (drawingmode & 16384) 3d Polygon Text
Type:
bitfield

lightlayer

Light layers this material affects.
Type:
bitfield.

linearsubsurf

True if the subdivision method does not alter the shape of the mesh. linearsubsurf is used to increase lighting quality.

material

Material name
Type:
string

shininess

The shininess (specular exponent) of the material. 0.0 <= shininess <= 128.0
Type:
float

smooth

See "Set Smooth/Set Solid" If smooth is false (Solid) and the mesh has armatures, the face normals will be recalculated. This is slower.
Type:
boolean

specular

The specular colour of the material. black = [0.0, 0.0, 0.0, 1.0] white = [1.0, 1.0, 1.0, 1.0]
Type:
list [r, g, b, a]

specularity

The amount of specular of the material. 0.0 <= specularity <= 1.0
Type:
float

subsurf

The amount of mesh smoothing to apply. This requires hardware support.
Type:
integer

texture

Texture name
Type:
string

tile

Texture is tiling
Type:
boolean

tilexrep

Number of tile repetitions in x direction.
Type:
integer

tileyrep

Number of tile repetitions in y direction.
Type:
integer

transparent

This material is transparent. All meshes with this material will be rendered after non transparent meshes from back to front.
Type:
boolean

triangle

Mesh data with this material is triangles.
Type:
boolean

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

   Home       Trees       Index       Help   

Blender GameEngine

Generated by Epydoc 2.1 on Sat Aug 28 03:09:59 2004 http://epydoc.sf.net