Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Color: Improve documentation about color management #29545

Merged
merged 3 commits into from
Oct 3, 2024
Merged

Color: Improve documentation about color management #29545

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f105f71
Color: Improve documentation about RGB range and color spaces
donmccurdy Oct 3, 2024
b8d2825
ColarManagement: clarification
donmccurdy Oct 3, 2024
756c2b7
address feedback, remove open domain mentions for now
donmccurdy Oct 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Color: Improve documentation about RGB range and color spaces
  • Loading branch information
@donmccurdy
donmccurdy committed Oct 3, 2024
commit f105f715a5a541b6113113064b288e59331f44af
84 changes: 63 additions & 21 deletions docs/api/en/math/Color.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,49 @@ <h1>[name]</h1>
<p class="desc">Class representing a color.</p>

<p>
Iterating through a [name] instance will yield its components (r, g, b) in
A Color instance is represented by RGB components in the linear <i>working
color space</i>, which defaults to `LinearSRGBColorSpace`. Inputs
conventionally using `SRGBColorSpace` (such as hexadecimals and CSS
strings) are converted to the working color space automatically.
</p>

<p>
<code>
// converted automically from SRGBColorSpace to LinearSRGBColorSpace
const color = new THREE.Color().setHex( 0x112233 );
</code>
</p>

<p>
Source color spaces may be specified explicitly, to ensure correct
conversions.
</p>

<p>
<code>
// assumed already LinearSRGBColorSpace; no conversion
const color = new THREE.Color().setRGB( 0.5, 0.5, 0.5 );

// converted explicitly from SRGBColorSpace to LinearSRGBColorSpace
const color = new THREE.Color().setRGB( 0.5, 0.5, 0.5, SRGBColorSpace );
</code>
</p>

<p>
If THREE.ColorManagement is disabled, no conversions occur. For details,
see <i>Color management</i>.
</p>

<p>
Minimum and maximum values of RGB components are context-dependent. For
example, components of [page:MeshStandardMaterial.color] represent a
diffuse reflectance fraction, and so must be in the range [0, 1].
In contrast, “unlit” or “self-lit” colors like [page:MeshBasicMaterial.color]
may be in the range [0, Infinity).
</p>

<p>
Iterating through a Color instance will yield its components (r, g, b) in
the corresponding order.
</p>

Expand Down Expand Up @@ -50,15 +92,15 @@ <h3>
[page:Color_Hex_or_String r] - (optional) If arguments [page:Float g] and
[page:Float b] are defined, the red component of the color. If they are
not defined, it can be a
[link:https://en.wikipedia.org/wiki/Web_colors#Hex_triplet hexadecimal triplet] (recommended),
[link:https://en.wikipedia.org/wiki/Web_colors#Hex_triplet hexadecimal triplet] (recommended),
a CSS-style string, or another `Color` instance.<br />
[page:Float g] - (optional) If it is defined, the green component of the
color.<br />
[page:Float b] - (optional) If it is defined, the blue component of the
color.<br /><br />

Note that standard method of specifying color in three.js is with a
[link:https://en.wikipedia.org/wiki/Web_colors#Hex_triplet hexadecimal triplet],
[link:https://en.wikipedia.org/wiki/Web_colors#Hex_triplet hexadecimal triplet],
and that method is used throughout the rest of the
documentation.<br /><br />

Expand Down Expand Up @@ -91,13 +133,13 @@ <h3>[property:Boolean isColor]</h3>
<p>Read-only flag to check if a given object is of type [name].</p>

<h3>[property:Float r]</h3>
<p>Red channel value between `0` and `1`. Default is `1`.</p>
<p>Red channel value, typically between `0` and `1`. Default is `1`.</p>
donmccurdy marked this conversation as resolved.
Show resolved Hide resolved

<h3>[property:Float g]</h3>
<p>Green channel value between `0` and `1`. Default is `1`.</p>
<p>Green channel value, typically between `0` and `1`. Default is `1`.</p>

<h3>[property:Float b]</h3>
<p>Blue channel value between `0` and `1`. Default is `1`.</p>
<p>Blue channel value, typically between `0` and `1`. Default is `1`.</p>

<h2>Methods</h2>

Expand Down Expand Up @@ -134,25 +176,25 @@ <h3>[method:this copy]( [param:Color color] )</h3>
</p>

<h3>[method:this convertLinearToSRGB]()</h3>
<p>Converts this color from linear space to sRGB space.</p>
<p>Converts this color from `LinearSRGBColorSpace` to `SRGBColorSpace`.</p>

<h3>[method:this convertSRGBToLinear]()</h3>
<p>Converts this color from sRGB space to linear space.</p>
<p>Converts this color from `SRGBColorSpace` to `LinearSRGBColorSpace`.</p>

<h3>[method:this copyLinearToSRGB]( [param:Color color] )</h3>
<p>
[page:Color color] — Color to copy.<br />

Copies the given color into this color, and then converts this color from
linear space to sRGB space.
`LinearSRGBColorSpace` to `SRGBColorSpace`.
</p>

<h3>[method:this copySRGBToLinear]( [param:Color color] )</h3>
<p>
[page:Color color] — Color to copy.<br />

Copies the given color into this color, and then converts this color from
sRGB space to linear space.
`SRGBColorSpace` to `LinearSRGBColorSpace`.
</p>

<h3>[method:Boolean equals]( [param:Color color] )</h3>
Expand Down Expand Up @@ -208,11 +250,11 @@ <h3>
object of the form:

<code>
{
h: 0,
s: 0,
l: 0
}
{
h: 0,
s: 0,
l: 0
}
</code>
</p>

Expand Down Expand Up @@ -253,9 +295,9 @@ <h3>
[page:Float alpha] - interpolation factor, typically in the closed
interval `[0, 1]`.<br /><br />

Sets this color to be the color linearly interpolated between [page:Color color1]
Sets this color to be the color linearly interpolated between [page:Color color1]
and [page:Color color2] where alpha is the percent distance along
the line connecting the two colors - alpha = 0 will be [page:Color color1],
the line connecting the two colors - alpha = 0 will be [page:Color color1],
and alpha = 1 will be [page:Color color2].
</p>

Expand Down Expand Up @@ -335,16 +377,16 @@ <h3>
[method:this setRGB]( [param:Float r], [param:Float g], [param:Float b], [param:string colorSpace] = LinearSRGBColorSpace )
</h3>
<p>
[page:Float r] — Red channel value between `0.0` and `1.0`.<br />
[page:Float g] — Green channel value between `0.0` and `1.0`.<br />
[page:Float b] — Blue channel value between `0.0` and `1.0`.<br /><br />
[page:Float r] — Red channel value, typically between `0` and `1`.<br />
[page:Float g] — Green channel value, typically between `0` and `1`.<br />
[page:Float b] — Blue channel value, typically between `0` and `1`.<br /><br />

Sets this color from RGB values.
</p>

<h3>[method:this setScalar]( [param:Float scalar] )</h3>
<p>
[page:Float scalar] — a value between `0.0` and `1.0`.<br /><br />
[page:Float scalar] — a value, typically between `0.0` and `1.0`.<br /><br />

Sets all three color components to the value [page:Float scalar].
</p>
Expand Down