Urho.Material Class

Describes how to render 3D geometries.

See Also: Material

Syntax

public class Material : Resource

Remarks

On the disk, they are XML data. Default and example materials exist in the bin/CoreData/Materials & bin/Data/Materials subdirectories, and techniques exist in the bin/CoreData/Techniques subdirectory.

A material defines the textures, shader parameters, the culling, fill mode to use, and refers to one or several techniques. A technique defines the actual rendering passes, the shaders to use in each, and all other rendering states such as depth test, depth write, and blending.

A material definition looks like this

XML Example

<material>
    <technique name="TechniqueName" quality="q" loddistance="d" />
    <texture unit="diffuse|normal|specular|emissive|environment" name="TextureName" />
    <texture ... />
    <parameter name="name" value="x y z w" />
    <parameter ... />
    <cull value="cw|ccw|none" />
    <shadowcull value="cw|ccw|none" />
    <fill value="solid|wireframe|point" />
    <depthbias constant="x" slopescaled="y" />
</material>

Several techniques can be defined for different quality levels and LOD distances. Technique quality levels are specified from 0 (low) to 2 (high). When rendering, the highest available technique that does not exceed the Renderer material quality setting will be chosen, see Renderer.MaterialQuality. It is also possible for a technique to require Shader Model 3, in this case it will be skipped on SM2 hardware.

The techniques for different LOD levels and quality settings must appear in a specific order:

Material shader parameters can be floats or vectors up to 4 components, or matrices.

Default culling mode is counterclockwise. The shadowcull element specifies the culling mode to use in the shadow pass. Note that material's depth bias settings do not apply in the shadow pass; during shadow rendering the light's depth bias is used instead.

Material Textures

Diffuse maps specify the surface color in the RGB channels. Optionally they can use the alpha channel for blending and alpha testing. They should preferably be compressed to DXT1 (no alpha or 1-bit alpha) or DXT5 (smooth alpha) format.

Normal maps encode the tangent-space surface normal for normal mapping. There are two options for storing normals, which require choosing the correct material technique, as the pixel shader is different in each case:

  • Store as RGB. In this case use the DiffNormal techniques. This is the default used by AssetImporter, to ensure no conversion of normal textures needs to happen.
  • Store as xGxR, ie. Y-component in the green channel, and X-component in the alpha. In this case use the DiffNormalPacked techniques: Z will be reconstructed in the pixel shader. This encoding lends itself well to DXT5 compression. To convert normal maps to this format, you can use AMD's The Compressonator utility, see http://developer.amd.com/Resources/archive/ArchivedTools/gpu/compressonator/Pages/default.aspx

Make sure the normal map is oriented correctly: an even surface should have the color value R 0.5 G 0.5 B 1.0.

Models using a normal-mapped material need to have tangent vectors in their vertex data; the easiest way to ensure this is to use the switch -t (generate tangents) when using either AssetImporter or OgreImporter to import models to Urho3D format. If there are no tangents, the light attenuation on the normal-mapped material will behave in a completely erratic fashion.

Specular maps encode the specular surface color as RGB. Note that deferred rendering is only able to use monochromatic specular intensity from the G channel, while forward and light pre-pass rendering use fully colored specular. DXT1 format should suit these textures well.

Textures can have an accompanying XML file which specifies load-time parameters, such as addressing, mipmapping, and number of mip levels to skip on each quality level:

XML Example

<texture>
    <address coord="u|v|w" mode="wrap|mirror|clamp|border" />
    <border color="r g b a" />
    <filter mode="nearest|bilinear|trilinear|anisotropic|default" />
    <mipmap enable="false|true" />
    <quality low="x" medium="y" high="z" />
    <srgb enable="false|true" />
</texture>

The sRGB flag controls both whether the texture should be sampled with sRGB to linear conversion, and if used as a rendertarget, pixels should be converted back to sRGB when writing to it. To control whether the backbuffer should use sRGB conversion on write, use the Graphics.SRGB property.

Material Textures

Using cube map textures requires an XML file to define the cube map face textures or layout. In this case the XML file is the texture resource name in material scripts or in LoadResource() calls.

Individual face textures are defined in the XML like this: (see bin/Data/Textures/Skybox.xml for an example)

XML Example

<cubemap>
    <face name="PositiveX_TextureName" />
    <face name="NegativeX_TextureName" />
    <face name="PositiveY_TextureName" />
    <face name="NegativeY_TextureName" />
    <face name="PositiveZ_TextureName" />
    <face name="NegativeZ_TextureName" />
</cubemap>

Using a single image texture and a layout is used like this:

XML Example

<cubemap>
    <image name="TextureName" layout="horizontal|horizontalnvidia|horizontalcross|verticalcross|blender" />
    </cubemap>

For the layout definitions, see http://www.cgtextures.com/content.php?action=tutorial&name=cubemaps and http://en.wikibooks.org/wiki/Blender_3D:_Noob_to_Pro/Build_a_skybox

Requirements

Namespace: Urho
Assembly: Urho (in Urho.dll)
Assembly Versions: 1.0.0.0

The members of Urho.Material are listed below.

See Also: Resource

Public Constructors

Constructs a new instance of Urho.Material which is tied to the Application.CurrentContext.
Constructs a new instance of Urho.Material, given a raw pointer to an unmanaged object
Constructs a new instance of Urho.Material linked to a specific Context.

Protected Constructors

Empty constructor, chain to this constructor when you provide your own constructor that sets the handle field.

Public Properties

AlphaToCoverageBoolean. Return alpha-to-coverage mode. Or Set alpha-to-coverage mode on all passes.
[read-only]
AuxViewFrameNumberUInt32. Return last auxiliary view rendered frame number.
CullModeCullMode. Return normal culling mode. Or Set culling mode.
DepthBiasBiasParameters. Return depth bias. Or Set depth bias.
FillModeFillMode. Return polygon fill mode. Or Set polygon fill mode. Interacts with the camera's fill mode setting so that the "least filled" mode will be used.
LineAntiAliasBoolean. Return whether line antialiasing is enabled. Or Set line antialiasing on/off. Has effect only on models that consist of line lists.
NumTechniquesUInt32. Return number of techniques. Or Set number of techniques.
OcclusionBoolean. Return whether should render occlusion.
PixelShaderDefinesString. Set additional pixel shader defines. Separate multiple defines with spaces. Setting defines at the material level causes technique(s) to be cloned as necessary.
RenderOrderByte. Return render order. Or Set 8-bit render order within pass. Default 128. Lower values will render earlier and higher values later, taking precedence over e.g. state and distance sorting.
SceneScene. Return the scene associated with the material for shader parameter animation updates. Or Associate the material with a scene to ensure that shader parameter animation happens in sync with scene update, respecting the scene time scale. If no scene is set, the global update events will be used.
[read-only]
ShaderParameterHashUInt32. Return shader parameter hash value. Used as an optimization to avoid setting shader parameters unnecessarily.
ShadowCullModeCullMode. Return culling mode for shadows. Or Set culling mode for shadows.
[read-only]
SpecularBoolean. Return whether should render specular.
[read-only]
override
TypeStringHash. Urho's type system type.
[read-only]
override
TypeNameString. Urho's low-level type name.
[read-only]
static
TypeNameStaticString. Urho's low-level type name, accessible as a static method.
[read-only]
static
TypeStaticStringHash. Urho's low-level type, accessible as a static method.
VertexShaderDefinesString. Set additional vertex shader defines. Separate multiple defines with spaces. Setting defines at the material level causes technique(s) to be cloned as necessary.

Public Methods

override
BeginLoad(File) : Boolean
override
BeginLoad(MemoryBuffer) : Boolean
Clone(String) : Material
Clone the material.
override
EndLoad() : Boolean
Finish resource loading. Always called from the main thread. Return true if successful.
static
FromColor(Color) : Material
Creates a material using NoTexture or NoTextureAlpha Technique with the specified color as a shader parameter "MatDiffColor".
static
FromColor(Color, Boolean) : Material
Creates a material from a given color. Unlit means the material won't be affected by any lights.
static
FromImage(String) : Material
Creates a material from a 2D Texture.
static
FromImage(String, String) : Material
Create a material from an image and a normal map using DiffNormal technique.
static
FromImage(Image, Boolean) : Material
GetPass(UInt32, String) : Pass
Return pass by technique index and pass name.
GetShaderParameterAnimation(String) : ValueAnimation
Return shader parameter animation.
GetShaderParameterAnimationSpeed(String) : Single
Return shader parameter animation speed.
GetShaderParameterAnimationWrapMode(String) : WrapMode
Return shader parameter animation wrap mode.
GetTechnique(UInt32) : Technique
Return technique by index.
GetTexture(TextureUnit) : Texture
Return texture by unit.
static
GetTextureUnitName(TextureUnit) : String
Return name for texture unit.
Load(XmlElement) : Boolean
MarkForAuxView(UInt32)
Mark material for auxiliary view rendering.
static
ParseShaderParameterValue(String) : Variant
Parse a shader parameter value from a string. Retunrs either a bool, a float, or a 2 to 4-component vector.
static
RegisterObject(Context)
Register object factory.
ReleaseShaders()
Reset all shader pointers.
RemoveShaderParameter(String)
Remove shader parameter.
override
Save(File) : Boolean
override
Save(MemoryBuffer) : Boolean
Save(XmlElement) : Boolean
SetShaderParameter(String, Int32)
Set shader parameter.
SetShaderParameter(String, Single)
Set shader parameter.
SetShaderParameter(String, String)
Set shader parameter.
SetShaderParameter(String, Color)
Set shader parameter.
SetShaderParameter(String, IntRect)
Set shader parameter.
SetShaderParameter(String, IntVector2)
Set shader parameter.
SetShaderParameter(String, Matrix3x4)
Set shader parameter.
SetShaderParameter(String, Matrix4)
Set shader parameter.
SetShaderParameter(String, Quaternion)
Set shader parameter.
SetShaderParameter(String, Vector2)
Set shader parameter.
SetShaderParameter(String, Vector3)
Set shader parameter.
SetShaderParameter(String, Vector4)
Set shader parameter.
SetShaderParameterAnimation(String, ValueAnimation, WrapMode, Single)
Set shader parameter animation.
SetShaderParameterAnimationSpeed(String, Single)
Set shader parameter animation speed.
SetShaderParameterAnimationWrapMode(String, WrapMode)
Set shader parameter animation wrap mode.
SetTechnique(UInt32, Technique, UInt32, Single)
Set technique.
SetTexture(TextureUnit, Texture)
Set texture.
SetUVTransform(Vector2, Single, Single)
Set texture coordinate transform.
SetUVTransform(Vector2, Single, Vector2)
Set texture coordinate transform.
static
SkyboxFromImage(String) : Material
Creates a material Skybox where all six elements of the skybox are set to the specified image.
static
SkyboxFromImages(String, String, String, String, String, String) : Material
Creates a material Skybox where all six elements of the skybox are specified.
SortTechniques()
Ensure that material techniques are listed in correct order.