materials.html 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303
  1. <!DOCTYPE html><html lang="en"><head>
  2. <meta charset="utf-8">
  3. <title>Materials</title>
  4. <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
  5. <meta name="twitter:card" content="summary_large_image">
  6. <meta name="twitter:site" content="@threejs">
  7. <meta name="twitter:title" content="Three.js – Materials">
  8. <meta property="og:image" content="https://threejs.org/files/share.png">
  9. <link rel="shortcut icon" href="/files/favicon_white.ico" media="(prefers-color-scheme: dark)">
  10. <link rel="shortcut icon" href="/files/favicon.ico" media="(prefers-color-scheme: light)">
  11. <link rel="stylesheet" href="/manual/resources/lesson.css">
  12. <link rel="stylesheet" href="/manual/resources/lang.css">
  13. </head>
  14. <body>
  15. <div class="container">
  16. <div class="lesson-title">
  17. <h1>Materials</h1>
  18. </div>
  19. <div class="lesson">
  20. <div class="lesson-main">
  21. <p>This article is part of a series of articles about three.js. The
  22. first article is <a href="fundamentals.html">three.js fundamentals</a>. If
  23. you haven't read that yet and you're new to three.js you might want to
  24. consider starting there.</p>
  25. <p>Three.js provides several types of materials.
  26. They define how objects will appear in the scene.
  27. Which materials you use really depends on what you're trying to
  28. accomplish.</p>
  29. <p>There are 2 ways to set most material properties. One at creation time which
  30. we've seen before.</p>
  31. <pre class="prettyprint showlinemods notranslate lang-js" translate="no">const material = new THREE.MeshPhongMaterial({
  32. color: 0xFF0000, // red (can also use a CSS color string here)
  33. flatShading: true,
  34. });
  35. </pre>
  36. <p>The other is after creation</p>
  37. <pre class="prettyprint showlinemods notranslate lang-js" translate="no">const material = new THREE.MeshPhongMaterial();
  38. material.color.setHSL(0, 1, .5); // red
  39. material.flatShading = true;
  40. </pre>
  41. <p>note that properties of type <a href="/docs/#api/en/math/Color"><code class="notranslate" translate="no">THREE.Color</code></a> have multiple ways to be set.</p>
  42. <pre class="prettyprint showlinemods notranslate lang-js" translate="no">material.color.set(0x00FFFF); // same as CSS's #RRGGBB style
  43. material.color.set(cssString); // any CSS color, eg 'purple', '#F32',
  44. // 'rgb(255, 127, 64)',
  45. // 'hsl(180, 50%, 25%)'
  46. material.color.set(someColor) // some other THREE.Color
  47. material.color.setHSL(h, s, l) // where h, s, and l are 0 to 1
  48. material.color.setRGB(r, g, b) // where r, g, and b are 0 to 1
  49. </pre>
  50. <p>And at creation time you can pass either a hex number or a CSS string</p>
  51. <pre class="prettyprint showlinemods notranslate lang-js" translate="no">const m1 = new THREE.MeshBasicMaterial({color: 0xFF0000}); // red
  52. const m2 = new THREE.MeshBasicMaterial({color: 'red'}); // red
  53. const m3 = new THREE.MeshBasicMaterial({color: '#F00'}); // red
  54. const m4 = new THREE.MeshBasicMaterial({color: 'rgb(255,0,0)'}); // red
  55. const m5 = new THREE.MeshBasicMaterial({color: 'hsl(0,100%,50%)'); // red
  56. </pre>
  57. <p>So let's go over three.js's set of materials.</p>
  58. <p>The <a href="/docs/#api/en/materials/MeshBasicMaterial"><code class="notranslate" translate="no">MeshBasicMaterial</code></a> is not affected by lights.
  59. The <a href="/docs/#api/en/materials/MeshLambertMaterial"><code class="notranslate" translate="no">MeshLambertMaterial</code></a> computes lighting only at the vertices vs the <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a> which computes lighting at every pixel. The <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a>
  60. also supports specular highlights.</p>
  61. <div class="spread">
  62. <div>
  63. <div data-diagram="MeshBasicMaterial"></div>
  64. <div class="code">Basic</div>
  65. </div>
  66. <div>
  67. <div data-diagram="MeshLambertMaterial"></div>
  68. <div class="code">Lambert</div>
  69. </div>
  70. <div>
  71. <div data-diagram="MeshPhongMaterial"></div>
  72. <div class="code">Phong</div>
  73. </div>
  74. </div>
  75. <div class="spread">
  76. <div>
  77. <div data-diagram="MeshBasicMaterialLowPoly"></div>
  78. </div>
  79. <div>
  80. <div data-diagram="MeshLambertMaterialLowPoly"></div>
  81. </div>
  82. <div>
  83. <div data-diagram="MeshPhongMaterialLowPoly"></div>
  84. </div>
  85. </div>
  86. <div class="threejs_center code">low-poly models with same materials</div>
  87. <p>The <code class="notranslate" translate="no">shininess</code> setting of the <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a> determines the <em>shininess</em> of the specular highlight. It defaults to 30.</p>
  88. <div class="spread">
  89. <div>
  90. <div data-diagram="MeshPhongMaterialShininess0"></div>
  91. <div class="code">shininess: 0</div>
  92. </div>
  93. <div>
  94. <div data-diagram="MeshPhongMaterialShininess30"></div>
  95. <div class="code">shininess: 30</div>
  96. </div>
  97. <div>
  98. <div data-diagram="MeshPhongMaterialShininess150"></div>
  99. <div class="code">shininess: 150</div>
  100. </div>
  101. </div>
  102. <p>Note that setting the <code class="notranslate" translate="no">emissive</code> property to a color on either a
  103. <a href="/docs/#api/en/materials/MeshLambertMaterial"><code class="notranslate" translate="no">MeshLambertMaterial</code></a> or a <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a> and setting the <code class="notranslate" translate="no">color</code> to black
  104. (and <code class="notranslate" translate="no">shininess</code> to 0 for phong) ends up looking just like the <a href="/docs/#api/en/materials/MeshBasicMaterial"><code class="notranslate" translate="no">MeshBasicMaterial</code></a>.</p>
  105. <div class="spread">
  106. <div>
  107. <div data-diagram="MeshBasicMaterialCompare"></div>
  108. <div class="code">
  109. <div>Basic</div>
  110. <div>color: 'purple'</div>
  111. </div>
  112. </div>
  113. <div>
  114. <div data-diagram="MeshLambertMaterialCompare"></div>
  115. <div class="code">
  116. <div>Lambert</div>
  117. <div>color: 'black'</div>
  118. <div>emissive: 'purple'</div>
  119. </div>
  120. </div>
  121. <div>
  122. <div data-diagram="MeshPhongMaterialCompare"></div>
  123. <div class="code">
  124. <div>Phong</div>
  125. <div>color: 'black'</div>
  126. <div>emissive: 'purple'</div>
  127. <div>shininess: 0</div>
  128. </div>
  129. </div>
  130. </div>
  131. <p>Why have all 3 when <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a> can do the same things as <a href="/docs/#api/en/materials/MeshBasicMaterial"><code class="notranslate" translate="no">MeshBasicMaterial</code></a>
  132. and <a href="/docs/#api/en/materials/MeshLambertMaterial"><code class="notranslate" translate="no">MeshLambertMaterial</code></a>? The reason is the more sophisticated material
  133. takes more GPU power to draw. On a slower GPU like say a mobile phone
  134. you might want to reduce the GPU power needed to draw your scene by
  135. using one of the less complex materials. It also follows that if you
  136. don't need the extra features then use the simplest material. If you don't
  137. need the lighting and the specular highlight then use the <a href="/docs/#api/en/materials/MeshBasicMaterial"><code class="notranslate" translate="no">MeshBasicMaterial</code></a>.</p>
  138. <p>The <a href="/docs/#api/en/materials/MeshToonMaterial"><code class="notranslate" translate="no">MeshToonMaterial</code></a> is similar to the <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a>
  139. with one big difference. Rather than shading smoothly it uses a gradient map
  140. (an X by 1 texture) to decide how to shade. The default uses a gradient map
  141. that is 70% brightness for the first 70% and 100% after but you can supply your
  142. own gradient map. This ends up giving a 2 tone look that looks like a cartoon.</p>
  143. <div class="spread">
  144. <div data-diagram="MeshToonMaterial"></div>
  145. </div>
  146. <p>Next up there are 2 <em>physically based rendering</em> materials. Physically Based
  147. Rendering is often abbreviated PBR.</p>
  148. <p>The materials above use simple math to make materials that look 3D but they
  149. aren't what actually happens in real world. The 2 PBR materials use much more
  150. complex math to come close to what actually happens in the real world.</p>
  151. <p>The first one is <a href="/docs/#api/en/materials/MeshStandardMaterial"><code class="notranslate" translate="no">MeshStandardMaterial</code></a>. The biggest difference between
  152. <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a> and <a href="/docs/#api/en/materials/MeshStandardMaterial"><code class="notranslate" translate="no">MeshStandardMaterial</code></a> is it uses different parameters.
  153. <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a> had a <code class="notranslate" translate="no">shininess</code> setting. <a href="/docs/#api/en/materials/MeshStandardMaterial"><code class="notranslate" translate="no">MeshStandardMaterial</code></a> has 2
  154. settings <code class="notranslate" translate="no">roughness</code> and <code class="notranslate" translate="no">metalness</code>.</p>
  155. <p>At a basic level <a href="/docs/#api/en/materials/MeshStandardMaterial#roughness"><code class="notranslate" translate="no">roughness</code></a> is the opposite
  156. of <code class="notranslate" translate="no">shininess</code>. Something that has a high roughness, like a baseball doesn't
  157. have hard reflections whereas something that's not rough, like a billiard ball,
  158. is very shiny. Roughness goes from 0 to 1.</p>
  159. <p>The other setting, <a href="/docs/#api/en/materials/MeshStandardMaterial#metalness"><code class="notranslate" translate="no">metalness</code></a>, says
  160. how metal the material is. Metals behave differently than non-metals. 0
  161. for non-metal and 1 for metal.</p>
  162. <p>Here's a quick sample of <a href="/docs/#api/en/materials/MeshStandardMaterial"><code class="notranslate" translate="no">MeshStandardMaterial</code></a> with <code class="notranslate" translate="no">roughness</code> from 0 to 1
  163. across and <code class="notranslate" translate="no">metalness</code> from 0 to 1 down.</p>
  164. <div data-diagram="MeshStandardMaterial" style="min-height: 400px"></div>
  165. <p>The <a href="/docs/#api/en/materials/MeshPhysicalMaterial"><code class="notranslate" translate="no">MeshPhysicalMaterial</code></a> is same as the <a href="/docs/#api/en/materials/MeshStandardMaterial"><code class="notranslate" translate="no">MeshStandardMaterial</code></a> but it
  166. adds a <code class="notranslate" translate="no">clearcoat</code> parameter that goes from 0 to 1 for how much to
  167. apply a clearcoat gloss layer and a <code class="notranslate" translate="no">clearCoatRoughness</code> parameter
  168. that specifies how rough the gloss layer is.</p>
  169. <p>Here's the same grid of <code class="notranslate" translate="no">roughness</code> by <code class="notranslate" translate="no">metalness</code> as above but with
  170. <code class="notranslate" translate="no">clearcoat</code> and <code class="notranslate" translate="no">clearCoatRoughness</code> settings.</p>
  171. <div data-diagram="MeshPhysicalMaterial" style="min-height: 400px"></div>
  172. <p>The various standard materials progress from fastest to slowest
  173. <a href="/docs/#api/en/materials/MeshBasicMaterial"><code class="notranslate" translate="no">MeshBasicMaterial</code></a> ➡ <a href="/docs/#api/en/materials/MeshLambertMaterial"><code class="notranslate" translate="no">MeshLambertMaterial</code></a> ➡ <a href="/docs/#api/en/materials/MeshPhongMaterial"><code class="notranslate" translate="no">MeshPhongMaterial</code></a> ➡
  174. <a href="/docs/#api/en/materials/MeshStandardMaterial"><code class="notranslate" translate="no">MeshStandardMaterial</code></a> ➡ <a href="/docs/#api/en/materials/MeshPhysicalMaterial"><code class="notranslate" translate="no">MeshPhysicalMaterial</code></a>. The slower materials
  175. can make more realistic looking scenes but you might need to design
  176. your code to use the faster materials on low powered or mobile machines.</p>
  177. <p>There are 3 materials that have special uses. <a href="/docs/#api/en/materials/ShadowMaterial"><code class="notranslate" translate="no">ShadowMaterial</code></a>
  178. is used to get the data created from shadows. We haven't
  179. covered shadows yet. When we do we'll use this material
  180. to take a peek at what's happening behind the scenes.</p>
  181. <p>The <a href="/docs/#api/en/materials/MeshDepthMaterial"><code class="notranslate" translate="no">MeshDepthMaterial</code></a> renders the depth of each pixel where
  182. pixels at negative <a href="/docs/#api/en/cameras/PerspectiveCamera#near"><code class="notranslate" translate="no">near</code></a> of the camera are 0 and negative <a href="/docs/#api/en/cameras/PerspectiveCamera#far"><code class="notranslate" translate="no">far</code></a> are 1. Certain special effects can use this data which we'll
  183. get into at another time.</p>
  184. <div class="spread">
  185. <div>
  186. <div data-diagram="MeshDepthMaterial"></div>
  187. </div>
  188. </div>
  189. <p>The <a href="/docs/#api/en/materials/MeshNormalMaterial"><code class="notranslate" translate="no">MeshNormalMaterial</code></a> will show you the <em>normals</em> of geometry.
  190. <em>Normals</em> are the direction a particular triangle or pixel faces.
  191. <a href="/docs/#api/en/materials/MeshNormalMaterial"><code class="notranslate" translate="no">MeshNormalMaterial</code></a> draws the view space normals (the normals relative to the camera).
  192. <span style="background: red;" class="color">x is red</span>,
  193. <span style="background: green;" class="dark-color">y is green</span>, and
  194. <span style="background: blue;" class="dark-color">z is blue</span> so things facing
  195. to the right will be <span style="background: #FF7F7F;" class="color">pink</span>,
  196. to the left will be <span style="background: #007F7F;" class="dark-color">aqua</span>,
  197. up will be <span style="background: #7FFF7F;" class="color">light green</span>,
  198. down will be <span style="background: #7F007F;" class="dark-color">purple</span>,
  199. and toward the screen will be <span style="background: #7F7FFF;" class="color">lavender</span>.</p>
  200. <div class="spread">
  201. <div>
  202. <div data-diagram="MeshNormalMaterial"></div>
  203. </div>
  204. </div>
  205. <p><a href="/docs/#api/en/materials/ShaderMaterial"><code class="notranslate" translate="no">ShaderMaterial</code></a> is for making custom materials using the three.js shader
  206. system. <a href="/docs/#api/en/materials/RawShaderMaterial"><code class="notranslate" translate="no">RawShaderMaterial</code></a> is for making entirely custom shaders with
  207. no help from three.js. Both of these topics are large and will be
  208. covered later.</p>
  209. <p>Most materials share a bunch of settings all defined by <a href="/docs/#api/en/materials/Material"><code class="notranslate" translate="no">Material</code></a>.
  210. <a href="/docs/#api/en/materials/Material">See the docs</a>
  211. for all of them but let's go over two of the most commonly used
  212. properties.</p>
  213. <p><a href="/docs/#api/en/materials/Material#flatShading"><code class="notranslate" translate="no">flatShading</code></a>:
  214. whether or not the object looks faceted or smooth. default = <code class="notranslate" translate="no">false</code>.</p>
  215. <div class="spread">
  216. <div>
  217. <div data-diagram="smoothShading"></div>
  218. <div class="code">flatShading: false</div>
  219. </div>
  220. <div>
  221. <div data-diagram="flatShading"></div>
  222. <div class="code">flatShading: true</div>
  223. </div>
  224. </div>
  225. <p><a href="/docs/#api/en/materials/Material#side"><code class="notranslate" translate="no">side</code></a>: which sides of triangles to show. The default is <code class="notranslate" translate="no">THREE.FrontSide</code>.
  226. Other options are <code class="notranslate" translate="no">THREE.BackSide</code> and <code class="notranslate" translate="no">THREE.DoubleSide</code> (both sides).
  227. Most 3D objects drawn in three are probably opaque solids so the back sides
  228. (the sides facing inside the solid) do not need to be drawn. The most common
  229. reason to set <code class="notranslate" translate="no">side</code> is for planes or other non-solid objects where it is
  230. common to see the back sides of triangles.</p>
  231. <p>Here are 6 planes drawn with <code class="notranslate" translate="no">THREE.FrontSide</code> and <code class="notranslate" translate="no">THREE.DoubleSide</code>.</p>
  232. <div class="spread">
  233. <div>
  234. <div data-diagram="sideDefault" style="height: 250px;"></div>
  235. <div class="code">side: THREE.FrontSide</div>
  236. </div>
  237. <div>
  238. <div data-diagram="sideDouble" style="height: 250px;"></div>
  239. <div class="code">side: THREE.DoubleSide</div>
  240. </div>
  241. </div>
  242. <p>There's really a lot to consider with materials and we actually still
  243. have a bunch more to go. In particular we've mostly ignored textures
  244. which open up a whole slew of options. Before we cover textures though
  245. we need to take a break and cover
  246. <a href="setup.html">setting up your development environment</a></p>
  247. <div class="threejs_bottombar">
  248. <h3>material.needsUpdate</h3>
  249. <p>
  250. This topic rarely affects most three.js apps but just as an FYI...
  251. Three.js applies material settings when a material is used where "used"
  252. means "something is rendered that uses the material". Some material settings are
  253. only applied once as changing them requires lots of work by three.js.
  254. In those cases you need to set <code class="notranslate" translate="no">material.needsUpdate = true</code> to tell
  255. three.js to apply your material changes. The most common settings
  256. that require you to set <code class="notranslate" translate="no">needsUpdate</code> if you change the settings after
  257. using the material are:
  258. </p>
  259. <ul>
  260. <li><code class="notranslate" translate="no">flatShading</code></li>
  261. <li>adding or removing a texture
  262. <p>
  263. Changing a texture is ok, but if want to switch from using no texture
  264. to using a texture or from using a texture to using no texture
  265. then you need to set <code class="notranslate" translate="no">needsUpdate = true</code>.
  266. </p>
  267. <p>In the case of going from texture to no-texture it is often
  268. just better to use a 1x1 pixel white texture.</p>
  269. </li>
  270. </ul>
  271. <p>As mentioned above most apps never run into these issues. Most apps
  272. do not switch between flat shaded and non flat shaded. Most apps also
  273. either use textures or a solid color for a given material, they rarely
  274. switch from using one to using the other.
  275. </p>
  276. </div>
  277. <p><canvas id="c"></canvas></p>
  278. <script type="module" src="../resources/threejs-materials.js"></script>
  279. </div>
  280. </div>
  281. </div>
  282. <script src="/manual/resources/prettify.js"></script>
  283. <script src="/manual/resources/lesson.js"></script>
  284. </body></html>