Package com.jme3.material

Class Material

java.lang.Object
com.jme3.material.Material
All Implemented Interfaces:
CloneableSmartAsset, Savable, Cloneable
public class Material extends Object implements CloneableSmartAsset, Cloneable, Savable
Material describes the rendering style for a given Geometry.

A material is essentially a list of parameters, those parameters map to uniforms which are defined in a shader. Setting the parameters can modify the behavior of a shader.

  • Field Details

  • Constructor Details

    • Material

      public Material(MaterialDef def)

    • Material

      public Material(AssetManager contentMan, String defName)

    • Material

      public Material()
      Do not use this constructor. Serialization purposes only.

  • Method Details

    • getAssetName

      public String getAssetName()
      Returns the asset key name of the asset from which this material was loaded.

      This value will be null unless this material was loaded from a .j3m file.

      Returns:
      Asset key name of the j3m file

    • getName

      public String getName()
      Returns:
      the name of the material (not the same as the asset name), the returned value can be null

    • setName

      public void setName(String name)
      This method sets the name of the material. The name is not the same as the asset name. It can be null and there is no guarantee of its uniqueness.
      Parameters:
      name - the name of the material

    • setKey

      public void setKey(AssetKey key)
      Description copied from interface: CloneableSmartAsset
      Assigns the specified AssetKey to the asset. This is invoked by the AssetManager. Only clones of the asset have non-null keys. The original copy that was loaded has no key assigned. Only the clones are tracked for garbage collection.
      Specified by:
      setKey in interface CloneableSmartAsset
      Parameters:
      key - The AssetKey to assign

    • getKey

      public AssetKey getKey()
      Description copied from interface: CloneableSmartAsset
      Returns the asset key that is used to track this asset for garbage collection.
      Specified by:
      getKey in interface CloneableSmartAsset
      Returns:
      the asset key that is used to track this asset for garbage collection.

    • getSortId

      public int getSortId()
      Returns the sorting ID or sorting index for this material.

      The sorting ID is used internally by the system to sort rendering of geometries. It sorted to reduce shader switches, if the shaders are equal, then it is sorted by textures.

      Returns:
      The sorting ID used for sorting geometries for rendering.

    • clone

      public Material clone()
      Clones this material. The result is returned.
      Specified by:
      clone in interface CloneableSmartAsset
      Overrides:
      clone in class Object
      Returns:
      A clone of this asset. The cloned asset cannot reference equal this asset.

    • contentEquals

      public boolean contentEquals(Object otherObj)
      Compares two materials and returns true if they are equal. This methods compare definition, parameters, additional render states. Since materials are mutable objects, implementing equals() properly is not possible, hence the name contentEquals().
      Parameters:
      otherObj - the material to compare to this material
      Returns:
      true if the materials are equal.

    • contentHashCode

      public int contentHashCode()
      Works like Object.hashCode() except it may change together with the material as the material is mutable by definition.
      Returns:
      value for use in hashing

    • getActiveTechnique

      public Technique getActiveTechnique()
      Returns the currently active technique.

      The technique is selected automatically by the RenderManager based on system capabilities. Users may select their own technique by using selectTechnique(java.lang.String, com.jme3.renderer.RenderManager).

      Returns:
      the currently active technique.
      See Also:

    • isTransparent

      public boolean isTransparent()
      Check if the transparent value marker is set on this material.
      Returns:
      True if the transparent value marker is set on this material.
      See Also:

    • setTransparent

      public void setTransparent(boolean transparent)
      Set the transparent value marker.

      This value is merely a marker, by itself it does nothing. Generally model loaders will use this marker to indicate further up that the material is transparent and therefore any geometries using it should be put into the transparent bucket.

      Parameters:
      transparent - the transparent value marker.

    • isReceivesShadows

      public boolean isReceivesShadows()
      Check if the material should receive shadows or not.
      Returns:
      True if the material should receive shadows.
      See Also:

    • setReceivesShadows

      public void setReceivesShadows(boolean receivesShadows)
      Set if the material should receive shadows or not.

      This value is merely a marker, by itself it does nothing. Generally model loaders will use this marker to indicate the material should receive shadows and therefore any geometries using it should have RenderQueue.ShadowMode.Receive set on them.

      Parameters:
      receivesShadows - if the material should receive shadows or not.

    • getAdditionalRenderState

      public RenderState getAdditionalRenderState()
      Acquire the additional render state to apply for this material.

      The first call to this method will create an additional render state which can be modified by the user to apply any render states in addition to the ones used by the renderer. Only render states which are modified in the additional render state will be applied.

      Returns:
      The additional render state.

    • getMaterialDef

      public MaterialDef getMaterialDef()
      Get the material definition (j3md file info) that this material is implementing.
      Returns:
      the material definition this material implements.

    • getParam

      public MatParam getParam(String name)
      Returns the parameter set on this material with the given name, returns null if the parameter is not set.
      Parameters:
      name - The parameter name to look up.
      Returns:
      The MatParam if set, or null if not set.

    • getParamValue

      public <T> T getParamValue(String name)
      Returns the current parameter's value.
      Type Parameters:
      T - the expected type of the parameter value
      Parameters:
      name - the parameter name to look up.
      Returns:
      current value or null if the parameter wasn't set.

    • getTextureParam

      public MatParamTexture getTextureParam(String name)
      Returns the texture parameter set on this material with the given name, returns null if the parameter is not set.
      Parameters:
      name - The parameter name to look up.
      Returns:
      The MatParamTexture if set, or null if not set.

    • getParams

      public Collection<MatParam> getParams()
      Returns a collection of all parameters set on this material.
      Returns:
      a collection of all parameters set on this material.
      See Also:

    • getParamsMap

      public ListMap<String,MatParam> getParamsMap()
      Returns the ListMap of all parameters set on this material.
      Returns:
      a ListMap of all parameters set on this material.
      See Also:

    • setParam

      public void setParam(String name, VarType type, Object value)
      Pass a parameter to the material shader.
      Parameters:
      name - the name of the parameter defined in the material definition (j3md)
      type - the type of the parameter VarType
      value - the value of the parameter

    • clearParam

      public void clearParam(String name)
      Clear a parameter from this material. The parameter must exist
      Parameters:
      name - the name of the parameter to clear

    • setTextureParam

      public void setTextureParam(String name, VarType type, Texture value)
      Set a texture parameter.
      Parameters:
      name - The name of the parameter
      type - The variable type VarType
      value - The texture value of the parameter.
      Throws:
      IllegalArgumentException - is value is null

    • setTexture

      public void setTexture(String name, Texture value)
      Pass a texture to the material shader.
      Parameters:
      name - the name of the texture defined in the material definition (j3md) (for example Texture for Lighting.j3md)
      value - the Texture object previously loaded by the asset manager

    • setMatrix4

      public void setMatrix4(String name, Matrix4f value)
      Pass a Matrix4f to the material shader.
      Parameters:
      name - the name of the matrix defined in the material definition (j3md)
      value - the Matrix4f object

    • setBoolean

      public void setBoolean(String name, boolean value)
      Pass a boolean to the material shader.
      Parameters:
      name - the name of the boolean defined in the material definition (j3md)
      value - the boolean value

    • setFloat

      public void setFloat(String name, float value)
      Pass a float to the material shader.
      Parameters:
      name - the name of the float defined in the material definition (j3md)
      value - the float value

    • setFloat

      public void setFloat(String name, Float value)
      Pass a float to the material shader. This version avoids auto-boxing if the value is already a Float.
      Parameters:
      name - the name of the float defined in the material definition (j3md)
      value - the float value

    • setInt

      public void setInt(String name, int value)
      Pass an int to the material shader.
      Parameters:
      name - the name of the int defined in the material definition (j3md)
      value - the int value

    • setColor

      public void setColor(String name, ColorRGBA value)
      Pass a Color to the material shader.
      Parameters:
      name - the name of the color defined in the material definition (j3md)
      value - the ColorRGBA value

    • setUniformBufferObject

      public void setUniformBufferObject(String name, BufferObject value)
      Pass an uniform buffer object to the material shader.
      Parameters:
      name - the name of the buffer object defined in the material definition (j3md).
      value - the buffer object.

    • setShaderStorageBufferObject

      public void setShaderStorageBufferObject(String name, BufferObject value)
      Pass a shader storage buffer object to the material shader.
      Parameters:
      name - the name of the buffer object defined in the material definition (j3md).
      value - the buffer object.

    • setVector2

      public void setVector2(String name, Vector2f value)
      Pass a Vector2f to the material shader.
      Parameters:
      name - the name of the Vector2f defined in the material definition (j3md)
      value - the Vector2f value

    • setVector3

      public void setVector3(String name, Vector3f value)
      Pass a Vector3f to the material shader.
      Parameters:
      name - the name of the Vector3f defined in the material definition (j3md)
      value - the Vector3f value

    • setVector4

      public void setVector4(String name, Vector4f value)
      Pass a Vector4f to the material shader.
      Parameters:
      name - the name of the Vector4f defined in the material definition (j3md)
      value - the Vector4f value

    • selectTechnique

      public void selectTechnique(String name, RenderManager renderManager)
      Select the technique to use for rendering this material.

      Any candidate technique for selection (either default or named) must be verified to be compatible with the system, for that, the renderManager is queried for capabilities.

      Parameters:
      name - The name of the technique to select, pass TechniqueDef.DEFAULT_TECHNIQUE_NAME to select one of the default techniques.
      renderManager - The render manager to query for capabilities.
      Throws:
      IllegalArgumentException - If no technique exists with the given name.
      UnsupportedOperationException - If no candidate technique supports the system capabilities.

    • preload

      public void preload(RenderManager renderManager, Geometry geometry)
      Preloads this material for the given render manager.

      Preloading the material can ensure that when the material is first used for rendering, there won't be any delay since the material has been already been setup for rendering.

      Parameters:
      renderManager - The render manager to preload for
      geometry - to determine the applicable parameter overrides, if any

    • render

      public void render(Geometry geometry, LightList lights, RenderManager renderManager)
      Called by RenderManager to render the geometry by using this material.

      The material is rendered as follows:

      • Determine which technique to use to render the material - either what the user selected via Material.selectTechnique(), or the first default technique that the renderer supports (based on the technique's requested rendering capabilities)
        • If the technique has been changed since the last frame, then it is notified via Technique.makeCurrent(). If the technique wants to use a shader to render the model, it should load it at this part - the shader should have all the proper defines as declared in the technique definition, including those that are bound to material parameters. The technique can re-use the shader from the last frame if no changes to the defines occurred.
      • Set the RenderState to use for rendering. The render states are applied in this order (later RenderStates override earlier RenderStates):
        1. Technique Definition's RenderState - i.e. specific RenderState that is required for the shader.
        2. Material Instance Additional RenderState - i.e. ad-hoc RenderState set per model
        3. RenderManager's Forced RenderState - i.e. RenderState requested by a SceneProcessor or post-processing filter.
      • If the technique uses a shader, then the uniforms of the shader must be updated.
        • Uniforms bound to material parameters are updated based on the current material parameter values.
        • Uniforms bound to world parameters are updated from the RenderManager. Internally UniformBindingManager is used for this task.
        • Uniforms bound to textures will cause the texture to be uploaded as necessary. The uniform is set to the texture unit where the texture is bound.
      • If the technique uses a shader, the model is then rendered according to the lighting mode specified on the technique definition.
        • single pass light mode fills the shader's light uniform arrays with the first 4 lights and renders the model once.
        • multi pass light mode light mode renders the model multiple times, for the first light it is rendered opaque, on subsequent lights it is rendered with alpha-additive blending and depth writing disabled.
      • For techniques that do not use shaders, fixed function OpenGL is used to render the model (see GLRenderer interface):
        • OpenGL state that is bound to material parameters is updated.
        • The texture set on the material is uploaded and bound. Currently only 1 texture is supported for fixed function techniques.
        • If the technique uses lighting, then OpenGL lighting state is updated based on the light list on the geometry, otherwise OpenGL lighting is disabled.
        • The mesh is uploaded and rendered.
      Parameters:
      geometry - The geometry to render
      lights - Presorted and filtered light list to use for rendering
      renderManager - The render manager requesting the rendering

    • render

      public void render(Geometry geom, RenderManager rm)
      Called by RenderManager to render the geometry by using this material. Note that this version of the render method does not perform light filtering.
      Parameters:
      geom - The geometry to render
      rm - The render manager requesting the rendering

    • write

      public void write(JmeExporter ex) throws IOException
      Specified by:
      write in interface Savable
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • read

      public void read(JmeImporter im) throws IOException
      Specified by:
      read in interface Savable
      Throws:
      IOException