fix xrefs

docs/modules/tutorials/pages/intermediate/how_to_use_materials.adoc

@@ -1,11 +1,7 @@
 = How to Use Materials
-:author: 
-:revnumber: 
-:revdate: 2016/03/17 20:48
+:revnumber: 2.0
+:revdate: 2020/07/13
 :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.)
@@ -14,15 +10,15 @@ A Geometry (mesh) is just the shape of the object. jMonkeyEngine cannot render a
 *  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. 
+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 xref:Root:jme3/advanced/materials_overview.adoc[Material properties] they intend to use in their 3D models. You must have an understanding what <<terminology.adoc#materials-textures,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.
+Don't forget to add a xref:Root:jme3/advanced/light_and_shadow.adoc[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)`. 
+If you want more advanced background info: You can learn more about xref:Root:jme3/advanced/material_definitions.adoc[Material Definitions] in general here. You can find the full list of Material Parameters in the xref:Root:jme3/advanced/materials_overview.adoc[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)`.
 
 
 
@@ -56,7 +52,7 @@ 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 
+Do you reuse Materials? You can xref:sdk:material_editing.adoc[store Material properties in a .j3m file] and load all properties in one line using
 
 [source,java]
 ----
@@ -68,7 +64,7 @@ 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. 
+Every Material must have at least Material Colors or Textures. Some optional material features also require a combination of both.
 
 
 
@@ -76,7 +72,7 @@ Every Material must have at least Material Colors or Textures. Some optional mat
 
 To give an unshaded material a color:
 
-*  Specify the color property 
+*  Specify the color property
 +
 [source,java]
 ----
@@ -85,14 +81,14 @@ mat.setColor("Color", ColorRGBA.Blue); // with Unshaded.j3md
 
 To give an Phong-illuminated material a color:
 
-.  Activate material colors: 
+.  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. 
+.  Specify at least Diffuse and Ambient colors. Set both to the same color in the standard case.
 +
 [source,java]
 ----
@@ -106,7 +102,7 @@ mat.setColor("Ambient", ColorRGBA.Blue ); // with Lighting.j3md
 
 To give an unshaded material a texture:
 
-*  Specify at least a ColorMap: 
+*  Specify at least a ColorMap:
 +
 [source,java]
 ----
@@ -115,7 +111,7 @@ mat.setTexture("ColorMap", assetManager.loadTexture("Textures/monkey.png")); //
 
 To give a Phong-illuminated material a texture:
 
-*  Specify at least the DiffuseMap texture: 
+*  Specify at least the DiffuseMap texture:
 +
 [source,java]
 ----
@@ -124,7 +120,7 @@ mat.setTexture("DiffuseMap", assetManager.loadTexture("Textures/wood_diffuse.png
 
 [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). 
+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]
 ----
@@ -142,14 +138,14 @@ A NormalMap (also called BumpMap) is an extra colored texture that describes the
 
 To add a BumpMap (this only makes sense for illuminated Materials):
 
-.  Generate normal vectors information for the Mesh (not for the Geometry!) using `com.jme3.util.TangentBinormalGenerator`. 
+.  Generate normal vectors information for the Mesh (not for the Geometry!) using `com.jme3.util.TangentBinormalGenerator`.
 +
 [source,java]
 ----
 TangentBinormalGenerator.generate(mesh);
 ----
 
-.  Specify the `NormalMap` texture for the Material. 
+.  Specify the `NormalMap` texture for the Material.
 +
 [source,java]
 ----
@@ -171,7 +167,7 @@ Shininess is a float value between 1 (rough surface with blurry shininess) and 1
 mat.setFloat("Shininess", 5f);
 ----
 
-.  Activate material colors: 
+.  Activate material colors:
 +
 [source,java]
 ----
@@ -188,7 +184,7 @@ mat.setColor("Diffuse",ColorRGBA.White);
 ----
 
 .  (Optional) Specify a `SpecularMap` texture. +
-You optionally hand-draw this grayscale texture to outline in detail where the surface should be more shiny (whiter grays) and where less (blacker grays). If you don't supply a SpecularMap, the whole material is shiny everywhere. 
+You optionally hand-draw this grayscale texture to outline in detail where the surface should be more shiny (whiter grays) and where less (blacker grays). If you don't supply a SpecularMap, the whole material is shiny everywhere.
 +
 [source,java]
 ----
@@ -210,7 +206,7 @@ mat.setColor("Specular",ColorRGBA.Black);
 
 To activate glow:
 
-.  Add one <<jme3/advanced/bloom_and_glow#,BloomFilter PostProcessor>> in your simpleInitApp() method (only once, it is used by all glowing objects).
+.  Add one xref:Root:jme3/advanced/bloom_and_glow.adoc[BloomFilter PostProcessor] in your simpleInitApp() method (only once, it is used by all glowing objects).
 +
 [source,java]
 ----
@@ -229,7 +225,7 @@ mat.setColor("GlowColor",ColorRGBA.White);
 ----
 
 .  (Optional) Specify a `GlowMap` texture. +
-This texture outlines in detail where the DiffuseMap texture glows. If you don't supply a GlowMap, the whole material glows everwhere.  
+This texture outlines in detail where the DiffuseMap texture glows. If you don't supply a GlowMap, the whole material glows everwhere.
 +
 [source,java]
 ----
@@ -245,7 +241,7 @@ To deactivate glow:
 mat.setColor("GlowColor", ColorRGBA.Black);
 ----
 
-Learn more about <<jme3/advanced/bloom_and_glow#,Bloom and Glow>>.
+Learn more about xref:Root:jme3/advanced/bloom_and_glow.adoc[Bloom and Glow].
 
 
 
@@ -253,35 +249,35 @@ Learn more about <<jme3/advanced/bloom_and_glow#,Bloom and Glow>>.
 
 Most Material Definitions support an alpha channel to make a model opaque, translucent, or transparent.
 
-*  Alpha=1.0f makes the color opaque (default), 
+*  Alpha=1.0f makes the color opaque (default),
 *  Alpha=0.0f make the color fully transparent
 *  Alpha between 0f and 1f makes the color more or less translucent.
 
 To make a Geometry transparent or translucent:
 
 .  Specify which areas you want to be transparent or translucent by specifying the alpha channel:
-**  (For colored Materials) In any RGBA color, the first three are Red-Green-Blue, and the last float is the Alpha channel. For example, to replace ColorRGBA.Red with a translucent red: 
+**  (For colored Materials) In any RGBA color, the first three are Red-Green-Blue, and the last float is the Alpha channel. For example, to replace ColorRGBA.Red with a translucent red:
 +
 [source,java]
 ----
 mat.setColor("Color", new ColorRGBA(1,0,0,0.5f));
 ----
 
-**  (For textured Materials) Supply an AlphaMap that outlines which areas are transparent. 
+**  (For textured Materials) Supply an AlphaMap that outlines which areas are transparent.
 +
 [source,java]
 ----
 mat.setTexture("AlphaMap", assetManager.loadTexture("Textures/window_alpha.png"));
 ----
 
-**  (For textured Materials) If the DiffuseMap has an alpha channel, use: 
+**  (For textured Materials) If the DiffuseMap has an alpha channel, use:
 +
 [source,java]
 ----
 mat.setBoolean("UseAlpha",true);
 ----
 
-.  Specify BlendMode Alpha for the Material. 
+.  Specify BlendMode Alpha for the Material.
 +
 [source,java]
 ----
@@ -289,18 +285,18 @@ mat.getAdditionalRenderState().setBlendMode(BlendMode.Alpha);
 ----
 
 .  Put the Geometry (not the Material!) in the appropriate render queue bucket. +
-**  Objects in the translucent bucket (e.g. particles) are not affected by SceneProcessors (e.g. shadows).  
+**  Objects in the translucent bucket (e.g. particles) are not affected by SceneProcessors (e.g. shadows).
 +
 [source,java]
 ----
-geo.setQueueBucket(Bucket.Translucent); 
+geo.setQueueBucket(Bucket.Translucent);
 ----
 
 **  Objects in the transparent bucket (e.g. foliage) are affected by SceneProcessors (e.g. shadows).
 +
 [source,java]
 ----
-geo.setQueueBucket(Bucket.Transparent); 
+geo.setQueueBucket(Bucket.Transparent);
 ----
 
 .  (Optional) Specify other material settings.
@@ -318,7 +314,7 @@ a|Use for all opaque objects like walls, floors, people…
 
 a|getAdditionalRenderState().setBlendMode(BlendMode.Alpha);
 a|Interpolates the background pixel with the current pixel by using the current pixel's alpha.
-a|This is the most commonly used BlendMode for transparency and translucency: Frosted window panes, ice, glass, alpha-blended vegetation textures… 
+a|This is the most commonly used BlendMode for transparency and translucency: Frosted window panes, ice, glass, alpha-blended vegetation textures…
 
 a|getAdditionalRenderState().setDepthWrite(false);
 a|Disables writing of the pixel's depth value to the depth buffer.
@@ -326,7 +322,7 @@ a|Deactivate this on Materials if you expect two or more transparent/translucent
 
 a|getAdditionalRenderState().setAlphaTest(true) +
 getAdditionalRenderState().setAlphaFallOff(0.5f);
-a|Enables Alpha Testing and uses an AlphaDiscardThreshold as alpha fall-off value. This means that gradients in the AlphaMap are no longer interpreted as soft translucency, but parts of the texture become either fully opaque or fully transparent. Only pixels above the alpha threshold (e.g. 0.5f) are rendered. 
+a|Enables Alpha Testing and uses an AlphaDiscardThreshold as alpha fall-off value. This means that gradients in the AlphaMap are no longer interpreted as soft translucency, but parts of the texture become either fully opaque or fully transparent. Only pixels above the alpha threshold (e.g. 0.5f) are rendered.
 a|Activate Alpha Testing for (partially) *transparent* objects such as foliage, hair, etc. +
 Deactivate Alpha Testing for gradually *translucent* objects, such as colored glass, smoked glass, ghosts.
 
@@ -334,14 +330,14 @@ Deactivate Alpha Testing for gradually *translucent* objects, such as colored gl
 
 [TIP]
 ====
-It is possible to load a DiffuseMap texture that has an Alpha channel, and combine it with an underlying Material Color. 
+It is possible to load a DiffuseMap texture that has an Alpha channel, and combine it with an underlying Material Color.
 
 [source,java]
 ----
 mat.setBoolean("UseAlpha",true);
 ----
 
-The Material Color bleeds through the transparent areas of the top-layer DiffuseMap texture. In this case you do not need BlendMode Alpha – because it's not the whole Material that is transparent, but only one of the texture layers. You use this bleed-through effect, for example, to generate differently colored uniforms, animals, or plants, where each Material uses the same “template DiffuseMap texture but combines it with a different color.
+The Material Color bleeds through the transparent areas of the top-layer DiffuseMap texture. In this case you do not need BlendMode Alpha – because it's not the whole Material that is transparent, but only one of the texture layers. You use this bleed-through effect, for example, to generate differently colored uniforms, animals, or plants, where each Material uses the same "`template`" DiffuseMap texture but combines it with a different color.
 ====
 
 
@@ -358,7 +354,7 @@ a|Example
 
 a|getAdditionalRenderState().setWireframe(true);
 a|Switch to showing the (textured) Material in wireframe mode. The wireframe optionally uses the Material's `Color` value.
-a|Use wireframes to debug meshes, or for a “matrix or “holodeck effect.
+a|Use wireframes to debug meshes, or for a "`matrix`" or "`holodeck`" effect.
 
 a|getAdditionalRenderState().setLineWidth(2f);
 a|When in wireframe mode, sets the line width of the mesh.