-
Notifications
You must be signed in to change notification settings - Fork 0
Material and environment
In practice, when rendering, you are specifying what (the shape) to render and how (the material) to render. The shape is specified using the Mesh (or more commonly the MeshPart), which defines the vertices attributes for the shader. The material is most commonly used to specify the uniform values for the shader.
Uniforms can be grouped into model specific (e.g. the texture applied or whether or not to use blending) and environmental uniforms (e.g. the lights being applied or an environment cubemap). Likewise the 3D api allows you to specify a material and environment.
Materials are model (or modelinstance) specific. You can access them by index model.materials.get(0)
, by name model.getMaterial("material3")
or by nodepart model.nodes.get(0).parts(0).material
. Materials are copied when creating a ModelInstance, meaning that changing the material of a ModelInstance will not affect the original Model or other ModelInstances.
The Material class extends the Attributes class, see below for more information about Attributes.
An Environment contains the uniform values specific for a location. For example, the lights are part of the Environment. Simple applications might use only Environment, while more complex applications might use multiple environments depending on the location of a ModelInstance. A ModelInstance (or Renderable) can only contain one Environment though.
The Environment class extends the Attributes class, see below for more information about Attributes.
Both the Environment and Material classes extend the Attributes the class. Most commonly, the Attributes class is used to specify uniform values. For example a TextureAttribute can be used to specify an uniform to bound for a shader. However, attributes don't have to be uniforms, for example DepthTestAttribute is used to alter the opengl state and doesn't set an uniform.
The Attributes class is most comparable with a Set. It can contain at most one value for each attribute, just like an uniform can only be set to one value. Theoretically both the Material and Environment can contain the same attribute, the actual behavior in this scenario depends on the shader used, but in most cases the Materials attribute will be used instead of the Environment attribute.
Every attribute has a type
long value, which is a bitmask used to identify the attribute. Therefor a complete material or environment can be represented with a single long, where each bit represents an attribute. Some attribute classes are dedicated to a single type value (bit). Others can be used for multiple type values (bits), in which case you must specify the type on construction. For example:
Attribute attribute = new ColorAttribute(ColorAttribute.Diffuse, Color.RED);
note that the ColorAttribute class contains a convenience method to do the same:
Attribute attribute = ColorAttribute.createDiffuse(Color.RED);
The most common actions for attributes are set
, has
, remove
, and get
.
You can use the set
method to add or change an attribute. If there is already an attribute of the same type if will be first removed, after which the new attribute is added. For example: material.set(FloatAttribute.createAlphaTest(0.25f));
Using the has
method it is possible to check if a specific attribute type is set. For example: material.has(FloatAttribute.AlphaTest);
. It is also possible to check for multiple attributes, for example: material.has(FloatAttribute.AlphaTest | ColorAttribute.Diffuse);
. In which case the has
method will only return true
if all attributes are set. Note that because the has
method uses a bitwise check it is quite fast and can be used prior to e.g. a call to remove
to ensure the attribute is actually set.
With the remove
method you can remove an attribute of a specific type, for example:
material.remove(FloatAttribute.AlphaTest);
. You can also remove multiple attributes at once, for example: material.remove(FloatAttribute.AlphaTest | ColorAttribute.Diffuse);
.
The get
method can be used to fetch an attribute of a specific type. For example: material.get(FloatAttribute.AlphaTest);
. If the attribute isn't set the get
method will return null
. Because the type implies the class, you can safely cast the result without checking: (FloatAttribute)material.get(FloatAttribute.AlphaTest);
. For convenience there's also a template method: material.get(FloatAttribute.class, FloatAttribute.AlphaTest);
.
Besides that you can also clear
(to remove all attributes), iterate (it implements Iterable<Attribute>
) and compare (it implements Comparator<Attribute>
, however the same
method provides additional options) attributes. The getMask()
method provides access to the mask containing all attributes, for example material.getMask() & FloatAttribute.AlphaTest == FloatAttribute.AlphaTest
is the same as material.has(FloatAttribute.AlphaTest)
.
It is possible to use a standard attribute class for a new custom type. For example when you want to use the ColorAttribute class to specify a custom type of color. There are three things you must consider in that case:
- Name your attribute type. Each attribute type must have an unique alias (name). You might want to (but don't have to) use the uniform name for that. The alias will also be used for debugging, e.g. when calling
attribute.toString()
. - Register your attribute type. This is to make sure there is only one attribute type for each bit. This can be done only from within the Attribute class or a subclass.
- Make ColorAttribute accept the custom type. The ColorAttribute class and most other attribute classes checks the type on construction, this allows you to cast attributes without having to check anything other then the type. For example
(ColorAttribute)material.get(ColorAttribute.Diffuse)
will always work because ColorAttribute is the only attribute accepting theColorAttribute.Diffuse
type.
Because of step 2 and 3, you must extend the Attribute class to add a custom attribute type:
public class MyColorAttribute extends ColorAttribute {
public final static String MyColorAlias = "myColor"; // step 1: name the type
public final static long MyColor = register(MyColorAlias); // step 2: register the type
static {
Mask |= MyColor; // step 3: Make ColorAttribute accept the type
}
}
You can then create the custom attribute type using:
Attribute attribute = new ColorAttribute(MyColorAttribute.MyColor, Color.RED);
It is possible to create a custom attribute, in which case the process is not much different from above. You must extend the Attribute class, register at least one type and of course add some data to pass on to the shader. For example to add an attribute to pass a double value to the shader:
public class DoubleAttribute extends Attribute {
public final static String MyDouble1Alias = "myDouble1";
public final static long MyDouble1 = register(MyDouble1Alias);
public final static String MyDouble2Alias = "myDouble2";
public final static long MyDouble2 = register(MyDouble2Alias);
protected static long Mask = MyDouble1 | MyDouble2;
/** Method to check whether the specified type is a valid DoubleAttribute type */
public static Boolean is(final long type) {
return (type & Mask) != 0;
}
public double value;
public DoubleAttribute(final long type) {
super(type);
if (!is(type))
throw new GdxRuntimeException("Invalid type specified");
}
public DoubleAttribute(final long type, final double value) {
this(type);
this.value = value;
}
}
Of course MyDouble1Alias
, MyDouble1
, "myDouble1"
, MyDouble2Alias
, MyDouble2
and "myDouble2"
should be replaced by a more meaningful description.
Like stated above its possible to create custom attributes. However, there are a few attributes already included, which are listed below.
By default the 3D api assumes everything is opaque. The BlendingAttribute
is most commonly used for materials (in case of environment it will change the default behavior) and can be used to specify that the material is or is not blended. The BlendingAttribute
doesn't require you to specify a type on construction, its type is always BlendingAttribute.Type
, unless it's extended. It contains four properties which can be specified:
-
blended
indicates whether or not the material should be treated as blended. This is primarily used for sorting, for example opaque objects are drawn prior to transparent objects. -
sourceFunction
OpenGL enum which specifies how the (incoming) red, green, blue, and alpha source blending factors are computed, by default it is set to GL_SRC_ALPHA. -
destFunction
OpenGL enum which specifies how the (existing) red, green, blue, and alpha destination blending factors are computed, by default it is set to GL_ONE_MINUS_SRC_ALPHA. For additive blending you might want to set it to GL_ONE. -
opacity
The amount of opacity (the source alpha value), ranging from 0 (fully transparent) to 1 (fully opaque).
The ColorAttribute
allows you to pass a color to the shader. For that it only contains one property: .color
. You can set the color during construction (it will be set by value) or using the .color.set(...)
method. The ColorAttribute
requires an attribute type to be specified, by default the following types are available:
ColorAttribute.Diffuse
ColorAttribute.Specular
ColorAttribute.Ambient
ColorAttribute.Emissive
ColorAttribute.Reflection
ColorAttribute.AmbientLight
ColorAttribute.Fog
Where the latter two are most commonly used for Environment, while the others or commonly used for Material.
To pass a Cubemap
to the shader the CubemapAttribute
can be used. It's value is the textureDescription
member which can be used to specify the cubemap along with other texture related values. The CubemapAttribute
requires an attribute type to be specified, by default the CubemapAttribute.EnvironmentMap
is the only valid type.
Just like the BlendingAttribute
, does the DepthTestAttribute
not require an attribute type. It is always DepthTestAttribute.Type
. The DepthTestAttribute
can be used to specify depth testing and writing, using the following properties:
-
depthFunc
The depth test function, or 0 (or GL_NONE) to disable depth test, by default it is GL10.GL_LEQUAL. -
depthRangeNear
Mapping of near clipping plane to window coordinates, by default 0.0 -
depthRangeFar
Mapping of far clipping plane to window coordinates, by default 1.0 -
depthMask
Whether or not to write to the depth buffer, enabled by default.
To pass a single floating point value to the shader, the FloatAttribute
can be used. The value can be specified on construction or using the .value
member. The FloatAttribute
requires an attribute type, which by default can be:
-
FloatAttribute.Shininess
Used for specular lighting. -
FloatAttribute.AlphaTest
Used to discard pixels when the alpha value is equal or below the specified value.
Similar to the FloatAttribute
class, the IntAttribute
allows you to pass an integer value to the shader. Likewise the .value
member can be used or the value can be set on construction. The IntAttribute
requires an attribute type, which by default can be:
-
IntAttribute.CullFace
OpenGL enum to specify face culling, either GL_NONE (no culling), GL_FRONT (only render back faces) or GL_BACK (only render front faces). The default depends on the shader, the default shader uses GL_BACK by default.
TextureAttribute
can be used to pass a Texture
to the shader. Just like the CubemapAttribute
it has a textureDescription
member which allows you to set the Texture
amongst some texture related values like repeat and filter. The TextureAttribute
requires an attribute type, which by default can be one of the following:
TextureAttribute.Diffuse
TextureAttribute.Specular
TextureAttribute.Bump
TextureAttribute.Normal
-
Developer's Guide
- Introduction
- Goals & Features
- Community & Support
- Contributing
- Games Built with Libgdx
- Prerequisites
- Gradle Project Setup, Running, Debugging and Packaging
- Project Setup, Running & Debugging
- Third Party Services
- Working from Source
- Using libgdx with other JVM languages
- The Application Framework
- A Simple Game
- File Handling
- Networking
- Preferences
- Input Handling
- Memory Management
- Audio
-
Graphics
- Configuration & Querying Graphics ??
- Fullscreen & VSync
- Continuous & Non-Continuous Rendering
- Clearing the Screen
- Take a Screenshot
- OpenGL ES Support * Configuration & Querying OpenGL ?? * Direct Access ?? * Utility Classes * Rendering Shapes * Textures & TextureRegions * Meshes * Shaders * Frame Buffer Objects
- 2D Graphics * SpriteBatch, TextureRegions, and Sprite * 2D Animation * Clipping, with the use of ScissorStack * Orthographic camera * Mapping Touch Coordinates ?? * Viewports * NinePatches * Bitmap Fonts * Distance field fonts * Using TextureAtlases * Pixmaps * Packing Atlases Offline * Packing Atlases at Runtime * 2D Particle Effects * Tile Maps * scene2d * scene2d.ui * Skin
- 3D Graphics * Quick Start * Models * Material and environment * 3D animations and skinning * Importing Blender models in LibGDX * Perspective Camera ?? * Picking ??
- Managing Your Assets
- Utilities
-
Math Utilities
- Interpolation
- Vectors, Matrices, Quaternions
- Circles, Planes, Rays, etc.
- Path interface & Splines
- Bounding Volumes ??
- Intersection & Overlap Testing ??
- Physics
- Tools
- Extensions
- Deploying your Application
- Building Libgdx ??
- Known Issues
- Articles
- Deprecated (May be outdated)