RFR: 8314147: Updated the PhongMaterial documentation [v6]

[Ambarish Rapte]

On Mon, 26 Feb 2024 16:41:05 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Overhaul to the `PhongMaterial` documentation (and a bit to its superclass `Material`). Except for the introduction, I divided the documentation into 3 sections: qualitative explanation, mathematical model (I wouldn't think it necessary, but the current doc explains it), and examples.
>> 
>> The reason for the verbosity of the doc is that I envisioned 2 target audiences for this class. One is a Java developer who wants to understand the terminology and workings of computer graphics or of the artists who are already familiar with this domain. (How many Java developers know what diffuse, specular and normal maps are?) The other is an artist who is already familiar with the domain, but wants to see how this class compares with other renderers. For this reason, I looked at the terminology used by engines like Blender, Maya, UE4 and Unity and tried to mention the comparisons (like bump vs. height vs. normal maps, or specular vs. roughness/smoothness).
>> 
>> The examples I chose and some of the schematics are not the best, looking at it retroactively, but I want to give enough time for reviewers and get this into 22.
>
> Nir Lisker has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fixed typo

Noticed a couple typos.

modules/javafx.graphics/src/main/java/javafx/scene/paint/PhongMaterial.java line 65:

> 63:  * {@code PhongMaterial} is not suitable for surfaces that act like mirrors and reflect their environment, such as
> 64:  * reflective metals, water, and reflective ceramics. Neither does light refract (bend) when passing through transparent
> 65:  * or translucnet materials such as water, glass, or ice. These materials rely on <i>Fresnel effects</i> that are not

Typo: translucnet-> translucent

modules/javafx.graphics/src/main/java/javafx/scene/paint/PhongMaterial.java line 211:

> 209:  * the interaction between the reflected light and the viewer position: <i>R⋅V</i>. As similarly explained in the
> 210:  * diffuse component section, the geometric contribution is strongest when the viewer is aligned with the reflection
> 211:  * vector and is non-existant when they are perpendicular.

Typo: non-existant -> non-existent

-------------

PR Review: https://git.openjdk.org/jfx/pull/1378#pullrequestreview-1903833417
PR Review Comment: https://git.openjdk.org/jfx/pull/1378#discussion_r1504425654
PR Review Comment: https://git.openjdk.org/jfx/pull/1378#discussion_r1504429803