Material

Last revision: ver. 5.1 - 10 December 2013

NOTE: Methods marked as v5.x are available only to omegalib version 5.x and above.

[[module cyclops | Python-Reference#module-cyclops]] extends [[Uniforms]]

Contains visual properties for an entity. Visual properties set through a material are applied after an effect definition, and override properties specified in the effect. See the effect and material reference page for more information.

Methods

Method(s)	Description
[[Material]] create() static	creates a new material object
setColor([[Color]] diffuse, [[Color]] emissive)	Sets the diffuse and emissive colors for this material. After calling setColor, the passed colors will override any color definition specified in the entity effect.
reset()	Resets all material properties to their default values. Colors and transparency will switch back to their default values (that is, whatever is specified in the entity effect. Uniforms attached to the material will not be deleted by this call. To delete uniforms, call removeAllUniforms.
parse(string definiton)
setProgram(string program)	Sets the shading program to be used by this material. See the Material Programs section below for a list of default programs. An empty string switches to the fixed-function pipeline for this material.
setAlpha(float value), float getAlpha()	Sets or gets the material alpha value. setAlpha only sets the value of the unif_Alpha uniform. By default, cyclops shaders use this uniform to modulate fragment alpha values after lighting (see postLightingSection/default.frag). This behavior can be modified by the user, redefining the @postLightingSection shader macro.
setPolygonOffset(float factor, float units)
setShininess(float value), float getShininess()
setGloss(float value), float getGloss()
Flags
setTransparent(bool value) bool isTransparent()	Sets or gets the transparent flag for this entity. setTransparent overrides a transparency flag specified in the entity effect.
setWireframe(bool value), bool isWireframe()
setDoubleFace(bool value), bool isDoubleFace()
setAdditive(bool value), bool isAdditive()
setDepthTestEnabled(bool value), bool isDepthTestEnabled()
setLit(bool value), bool getLit()	Enables or disables lighting for the material. This only supported by fixed-function materials. To disable lighting in shaded materials, add the @unlit macro to your surface shader. See the page for more information.
Textures
setDiffuseTexture(String texture), String getDiffuseTexture()
setNormalTexture(String texture), String getNormalTexture()
v5.0 setTexture(String texture, int stage, String uniform)	Attaches a texture to a custom texture stae, and sets a shader uniform to point to it. See This Example for Python Multitexturing
v5.2 setCamera([[Camera]] cam), [[Camera}} getCamera()	Sets or gets the camera that will draw this material. If no camera is specified all cameras will draw this material.

Constants

|---|---| Constant | Description CameraDrawExplicitMaterials | Use this flag on cameras that should only draw materials explicitly attached to them.

Example: material explicit draw

# Assume the following: 
# - m1, m2 are materials
# - e is an entity
# - c1, c2 are cameras
e.addMaterial(m1)
e.addMaterial(m2)

# c2 will draw entity e only using material m2
m2.setCamera(c2)
c2.setFlag(Material.CameraDrawExplicitMaterials)

# Since no material is explicitly associated with c1, c1 will NOT
# draw this entity.
# If the following line is commented, c1 will draw the entity using m1.
c1.setFlag(Material.CameraDrawExplicitMaterials)

Material Programs

The material class uses the shading program passed through the setProgram method. When no program is specified the fixed function pileine will be used. Using the fixed function is deprecated, and it not tested often in omegalib, so it is strongly suggested you always use a shading program with your materials.

You can create your custom shading programs: see the ProgramAsset class and the program management methods of SceneManager for the python API, and the page for more information on the shading program structure.

cyclops offers the following default shading programs that you can use with your materials:

Program Name	Description
colored	Draw untextured objects with diffuse and emissive constant colors
colored byvertex	Draw untextured objects with diffuse per-vertex color. The color must be specified in the source vertex data as a vertex attribute.
colored byvertex-emissive	Draw untextured objects with emissive per-vertex color. The color must be specified in the source vertex data as a vertex attribute.
colored envmap	Like colored, but modulates the final color by the sky box environment map (if present)
bump	Draw textured object with a normal map. Objects must have a tangent-space basis added as a vertex attributes to work with this shader.
textured	Draw textured object, with a texture applied as a diffuse component. The texture will be influenced by lighting.
textured emissive	Draw textured object, with a texture applied as an emissive component. The texture will not be influenced by lighting. The final color is still modulated by the object diffuse color, so you can control the brightness and color of the textured object using a diffuse color different than full white.
textured envmap	Like textured, but modulates the final color by the sky box environment map (if present)

Examples

Emissive textured material

b = BoxShape.create(1,1,1)
b.setPosition(0, 2, -2)

# Apply an emissive texture to the box.
mat = b.getMaterial()
mat.setProgram('textured-emissive')
mat.setDiffuseTexture('cyclops/test/omega-transparent.png')

# Use a gray diffuse color to make the texture 50% darker.
mat.setColor(Color(0.5, 0.5, 0.5), Color(1,1,1,1))