<commit_before>= How to Use Materials
:author: 
:revnumber: 
:revdate: 2016/03/17 20:48
:keywords: material, texture, effect, wireframe, light, documentation
:relfileprefix: ../../
:imagesdir: ../..
ifdef::env-github,env-browser[:outfilesuffix: .adoc]


A Geometry (mesh) is just the shape of the object. jMonkeyEngine cannot render a shape without knowing anything about its surface properties. You need to apply a color or texture to the surface of your Geometries to make them visible. In jMonkeyEngine, colors and textures are represented as Material objects. (An alternative would also be to load a model that includes materials generated by a mesh editor, such as Blender.)

*  All Geometries must have Materials that defines color or texture.
*  Each Material is based on a Material Definition file. +
Examples of included Material Definitions: Lighting.j3md, Unshaded.j3md

You want to make the most of your 3D models by specifying good looking material parameters. The developers must be in contact with the graphic designers regarding which of the <<jme3/advanced/materials_overview#,Material properties>> they intend to use in their 3D models. You must have an understanding what <<jme3/terminology#materialstextures,texture maps>> are, to be able to use texture-mapped materials. 


[IMPORTANT]
====
Don't forget to add a <<jme3/advanced/light_and_shadow#,Light Source>> to the scene! All Materials (except “Unshaded ones) are *invisible* without a light source.
====


If you want more advanced background info: You can learn more about <<jme3/advanced/material_definitions#,Material Definitions>> in general here. You can find the full list of Material Parameters in the <<jme3/advanced/materials_overview#,Material Definitions Properties>> overview. The following sections introduce you to the most commonly used cases. You typically initialize Material objects in the `simpleInitApp()` method, and configure them using the setters described here. Then load the Materials using `myGeometry.setMaterial(mat)`. 


== Code Sample

The following samples assume that you loaded a Geometry called myGeometry, and want to assign a material to it.

This example creates a simple unshaded blue material: Use it for abstract objects that need no illumination/shading, e.g. sky, +++<abbr title="Graphical User Interface">GUI</abbr>+++ and billboard nodes, tiles/cards, or toons.

[source,java]
----
Spatial myGeometry = assetManager.loadModel("Models/Teapot/Teapot.j3o");
Material mat = new Material(assetManager,  // Create new material and...
    "Common/MatDefs/Misc/Unshaded.j3md");  // ... specify .j3md file to use (unshaded).
mat.setColor("Color", ColorRGBA.Blue);     // Set some parameters, e.g. blue.
myGeometry.setMaterial(mat);               // Use new material on this Geometry.

----

This example creates a link:http://en.wikipedia.org/wiki/Phong_reflection_model[Phong]-illuminated blue material. Use it for illuminated, naturalistic objects, such as characters, buildings, terrains, vehicles. Needs a light source, otherwise it will be invisible.

[source,java]
----
Spatial myGeometry = assetManager.loadModel("Models/Teapot/Teapot.j3o");
Material mat = new Material(assetManager,  // Create new material and...
    "Common/MatDefs/Light/Lighting.j3md"); // ... specify .j3md file to use (illuminated).
mat.setBoolean("UseMaterialColors",true);  // Set some parameters, e.g. blue.
mat.setColor("Ambient", ColorRGBA.Blue);   // ... color of this object
mat.setColor("Diffuse", ColorRGBA.Blue);   // ... color of light being reflected
myGeometry.setMaterial(mat);               // Use new material on this Geometry.

----


[TIP]
====
Do you reuse Materials? You can <<sdk/material_editing#,store Material properties in a .j3m file>> and load all properties in one line using 

[source,java]
----
myGeometry.setMaterial( assetManager.loadMaterial("Materials/myMaterial.j3m"));
----


====



== Colored or Textured

Every Material must have at least Material Colors or Textures. Some optional material features also require a combination of both. 


=== Colored

To give an unshaded material a color:

.  Specify the color property 
+
[source,java]
----
mat.setColor("Color", ColorRGBA.Blue); // with Unshaded.j3md
----


To give an Phong-illuminated material a color:

.  Activate material colors: 
+
[source,java]
----
mat.setBoolean("UseMaterialColors",true); // with Lighting.j3md
----
+
.  Specify at least Diffuse and Ambient colors. Set both to the same color in the standard case. 
+
[source,java]
----
mat.setColor("Diffuse", ColorRGBA.Blue ); // with Lighting.j3md
mat.setColor("Ambient", ColorRGBA.Blue ); // with Lighting.j3md
----



=== Textured

To give an unshaded material a texture:

*  Specify at least a ColorMap: 
[source,java]
+
----
mat.setTexture("ColorMap", assetManager.loadTexture("Textures/monkey.png")); // with Unshaded.j3md
----
+

To give a Phong-illuminated material a texture:

*  Specify at least the DiffuseMap texture: 
+
[source,java]
----
mat.setTexture("DiffuseMap", assetManager.loadTexture("Textures/wood_diffuse.png")); // with Lighting.j3md
----



[TIP]
====
It can happen that you load textures at different scales, for example, your blades of grass may look as big as twigs, or your spaceship's heat tiles may look like small bathroom tiles. Then you need to adjust the texture scale, either bigger (> 1.0f) or smaller (< 1.0f). 

[source,java]
----
geometry.scaleTextureCoordinates(new Vector2f(0.5f, 0.5f));<commit_msg>Update how_to_use_materials.adoc<commit_after>= How to Use Materials
:author: 
:revnumber: 
:revdate: 2016/03/17 20:48
:keywords: material, texture, effect, wireframe, light, documentation
:relfileprefix: ../../
:imagesdir: ../..
ifdef::env-github,env-browser[:outfilesuffix: .adoc]


A Geometry (mesh) is just the shape of the object. jMonkeyEngine cannot render a shape without knowing anything about its surface properties. You need to apply a color or texture to the surface of your Geometries to make them visible. In jMonkeyEngine, colors and textures are represented as Material objects. (An alternative would also be to load a model that includes materials generated by a mesh editor, such as Blender.)

*  All Geometries must have Materials that defines color or texture.
*  Each Material is based on a Material Definition file. +
Examples of included Material Definitions: Lighting.j3md, Unshaded.j3md

You want to make the most of your 3D models by specifying good looking material parameters. The developers must be in contact with the graphic designers regarding which of the <<jme3/advanced/materials_overview#,Material properties>> they intend to use in their 3D models. You must have an understanding what <<jme3/terminology#materialstextures,texture maps>> are, to be able to use texture-mapped materials. 


[IMPORTANT]
====
Don't forget to add a <<jme3/advanced/light_and_shadow#,Light Source>> to the scene! All Materials (except “Unshaded ones) are *invisible* without a light source.
====


If you want more advanced background info: You can learn more about <<jme3/advanced/material_definitions#,Material Definitions>> in general here. You can find the full list of Material Parameters in the <<jme3/advanced/materials_overview#,Material Definitions Properties>> overview. The following sections introduce you to the most commonly used cases. You typically initialize Material objects in the `simpleInitApp()` method, and configure them using the setters described here. Then load the Materials using `myGeometry.setMaterial(mat)`. 


== Code Sample

The following samples assume that you loaded a Geometry called myGeometry, and want to assign a material to it.

This example creates a simple unshaded blue material: Use it for abstract objects that need no illumination/shading, e.g. sky, +++<abbr title="Graphical User Interface">GUI</abbr>+++ and billboard nodes, tiles/cards, or toons.

[source,java]
----
Spatial myGeometry = assetManager.loadModel("Models/Teapot/Teapot.j3o");
Material mat = new Material(assetManager,  // Create new material and...
    "Common/MatDefs/Misc/Unshaded.j3md");  // ... specify .j3md file to use (unshaded).
mat.setColor("Color", ColorRGBA.Blue);     // Set some parameters, e.g. blue.
myGeometry.setMaterial(mat);               // Use new material on this Geometry.

----

This example creates a link:http://en.wikipedia.org/wiki/Phong_reflection_model[Phong]-illuminated blue material. Use it for illuminated, naturalistic objects, such as characters, buildings, terrains, vehicles. Needs a light source, otherwise it will be invisible.

[source,java]
----
Spatial myGeometry = assetManager.loadModel("Models/Teapot/Teapot.j3o");
Material mat = new Material(assetManager,  // Create new material and...
    "Common/MatDefs/Light/Lighting.j3md"); // ... specify .j3md file to use (illuminated).
mat.setBoolean("UseMaterialColors",true);  // Set some parameters, e.g. blue.
mat.setColor("Ambient", ColorRGBA.Blue);   // ... color of this object
mat.setColor("Diffuse", ColorRGBA.Blue);   // ... color of light being reflected
myGeometry.setMaterial(mat);               // Use new material on this Geometry.

----


[TIP]
====
Do you reuse Materials? You can <<sdk/material_editing#,store Material properties in a .j3m file>> and load all properties in one line using 

[source,java]
----
myGeometry.setMaterial( assetManager.loadMaterial("Materials/myMaterial.j3m"));
----


====



== Colored or Textured

Every Material must have at least Material Colors or Textures. Some optional material features also require a combination of both. 


=== Colored

To give an unshaded material a color:

*  Specify the color property 
+
[source,java]
----
mat.setColor("Color", ColorRGBA.Blue); // with Unshaded.j3md
----

To give an Phong-illuminated material a color:

.  Activate material colors: 
+
[source,java]
----
mat.setBoolean("UseMaterialColors",true); // with Lighting.j3md
----

.  Specify at least Diffuse and Ambient colors. Set both to the same color in the standard case. 
+
[source,java]
----
mat.setColor("Diffuse", ColorRGBA.Blue ); // with Lighting.j3md
mat.setColor("Ambient", ColorRGBA.Blue ); // with Lighting.j3md
----



=== Textured

To give an unshaded material a texture:

*  Specify at least a ColorMap: 
+
[source,java]
----
mat.setTexture("ColorMap", assetManager.loadTexture("Textures/monkey.png")); // with Unshaded.j3md
----


To give a Phong-illuminated material a texture:

*  Specify at least the DiffuseMap texture: 
+
[source,java]
----
mat.setTexture("DiffuseMap", assetManager.loadTexture("Textures/wood_diffuse.png")); // with Lighting.j3md
----



[TIP]
====
It can happen that you load textures at different scales, for example, your blades of grass may look as big as twigs, or your spaceship's heat tiles may look like small bathroom tiles. Then you need to adjust the texture scale, either bigger (> 1.0f) or smaller (< 1.0f). 

[source,java]
----
geometry.scaleTextureCoordinates(new Vector2f(0.5f, 0.5f));
{'fraction_non_alphanumeric': 0.10780567685589519, 'fraction_numerical': 0.008005822416302766, 'mean_word_length': 4.227294341417023, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1563114', 'n_tokens_mistral': 3249, 'n_tokens_neox': 3094, 'n_words': 1222}