Blender V5.3
libocio_scope.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2026 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#include <cmath>
6#include <memory>
7#include <mutex>
8
9#include "libocio_view.hh"
10
11#include "BLI_math_matrix.hh"
12#include "BLI_string.hh"
13
14#include "OCIO_matrix.hh"
15#include "OCIO_scope.hh"
16
17namespace blender::ocio {
18
37
39static constexpr float SCOPE_SDR_IN_HDR_SCOPE = 0.75f;
40
45static constexpr float SCOPE_HDR_MAX_NITS = 10000.0f;
46
48static constexpr float SCOPE_SDR_WHITE_NITS = 100.0f;
49
55
57static constexpr float SCOPE_SRGB_A = 1.055f;
58static constexpr float SCOPE_SRGB_B = 0.055f;
59static constexpr float SCOPE_SRGB_GAMMA = 2.4f;
60
65static constexpr float SCOPE_HDR_B = 0.0368291f;
66static constexpr float SCOPE_HDR_C = 0.8882908f;
67static constexpr float SCOPE_HDR_D = 0.8307242f;
68
70static float linear_to_srgb(const float linear)
71{
72 if (linear <= 0.0031308f) {
73 return 12.92f * linear;
74 }
75 return SCOPE_SRGB_A * std::pow(linear, 1.0f / SCOPE_SRGB_GAMMA) - SCOPE_SRGB_B;
76}
77
79static float nits_to_scope_value(const float nits)
80{
81 const float linear = nits / SCOPE_SDR_WHITE_NITS;
82 if (linear <= 1.0f) {
84 }
85 return SCOPE_HDR_B * std::log(linear - SCOPE_HDR_C) + SCOPE_HDR_D;
86}
87
89{
90 static std::mutex mutex;
91 std::lock_guard lock(mutex);
92 if (scope_info_) {
93 return *scope_info_;
94 }
95
96 scope_info_ = std::make_unique<ScopeInfo>();
97
98 /* Also use HDR mapping for raw scene linear data that goes beyond 1, but
99 * maybe ideally it should have its own custom mapping with scene linear
100 * gamut to visualize scene linear rather than display values. */
101 scope_info_->is_hdr = is_hdr_ || is_data_;
102
103 /* Scope space uses the same gamut as the display space. */
104 double4x4 scope_gamut_to_rec709 = double4x4::identity();
105 switch (gamut_) {
106 case Gamut::Rec709:
107 case Gamut::Unknown:
108 break;
109 case Gamut::P3D65:
110 scope_gamut_to_rec709 = OCIO_XYZ_TO_REC709 * math::invert(OCIO_XYZ_TO_P3);
111 break;
112 case Gamut::Rec2020:
113 scope_gamut_to_rec709 = OCIO_XYZ_TO_REC709 * math::invert(OCIO_XYZ_TO_REC2020);
114 break;
115 }
116 scope_info_->scope_gamut_to_rec709 = float3x3(scope_gamut_to_rec709);
117
118 scope_info_->luma_coefficients = scope_info_->luma_coefficients *
119 scope_info_->scope_gamut_to_rec709;
120
121 /* Compute RGB to YCbCr matrix commonly used in video encoding, using
122 * either BT.709 (CICP matrix 1) or BT.2020 NCL (CICP matrix 9). */
123 float kr = 0.2126f;
124 float kb = 0.0722f;
125 if (gamut_ == Gamut::Rec2020) {
126 kr = 0.2627f;
127 kb = 0.0593f;
128 }
129 const float kg = 1.0f - kr - kb;
130 scope_info_->yuv_matrix = float3x3(
131 float3(kr, -kr / (2.0f * (1.0f - kb)), 0.5f),
132 float3(kg, -kg / (2.0f * (1.0f - kb)), -kg / (2.0f * (1.0f - kr))),
133 float3(kb, 0.5f, -kb / (2.0f * (1.0f - kr))));
134
135 if (scope_info_->is_hdr) {
136 /* HDR. */
137 scope_info_->view_transform_max_nits = max_nits();
138 if (scope_info_->view_transform_max_nits > 0) {
139 scope_info_->view_transform_max_nits_value = nits_to_scope_value(
140 scope_info_->view_transform_max_nits);
141 }
142
143 scope_info_->sdr_white_level = SCOPE_SDR_IN_HDR_SCOPE;
144
145 /* HDR: graticules at logarithmic nit values. */
146 Vector<int> nit_values = {0, 18 /* middle gray */, 100};
147 const int max_nits = (scope_info_->view_transform_max_nits) ?
148 scope_info_->view_transform_max_nits :
149 1000;
150 if (!nit_values.contains(max_nits)) {
151 nit_values.append(max_nits);
152 }
153 if (!nit_values.contains(10000)) {
154 nit_values.append(10000);
155 }
156
157 for (const int nits : nit_values) {
158 ScopeGraticule graticule;
159 graticule.value = nits_to_scope_value(nits);
160 if (is_data_) {
161 SNPRINTF(graticule.label, "%.2f", nits / 100.0f);
162 }
163 else {
164 SNPRINTF(graticule.label, "%d nits", nits);
165 }
166 scope_info_->graticules.append(graticule);
167 }
168 }
169 else {
170 /* SDR: evenly distributed graticules. */
171 const float values[] = {0.0f, 0.25f, 0.50f, 0.75f, 1.0f};
172 for (const float val : values) {
173 ScopeGraticule graticule;
174 graticule.value = val;
175 SNPRINTF(graticule.label, "%.2f", val);
176 scope_info_->graticules.append(graticule);
177 }
178 }
179
180 return *scope_info_;
181}
182
183void LibOCIOView::append_scope_space_transforms(OCIO_NAMESPACE::GroupTransformRcPtr &group,
184 const StringRefNull lin_cie_xyz_d65_name) const
185{
186 /* Matrix to convert from CIE XYZ D65 to linear display gamut. */
187 double4x4 xyz_to_display_gamut;
188 switch (gamut_) {
189 case Gamut::Rec709:
190 case Gamut::Unknown:
191 xyz_to_display_gamut = OCIO_XYZ_TO_REC709;
192 break;
193 case Gamut::P3D65:
194 xyz_to_display_gamut = OCIO_XYZ_TO_P3;
195 break;
196 case Gamut::Rec2020:
197 xyz_to_display_gamut = OCIO_XYZ_TO_REC2020;
198 break;
199 }
200
201 /* Convert from display colorspace to CIE XYZ D65. */
202 auto to_cie_xyz_d65 = OCIO_NAMESPACE::ColorSpaceTransform::Create();
203 to_cie_xyz_d65->setSrc(display_colorspace_->name().c_str());
204 to_cie_xyz_d65->setDst(lin_cie_xyz_d65_name.c_str());
205 group->appendTransform(to_cie_xyz_d65);
206
207 /* Convert from CIE XYZ D65 to linear display gamut. */
208 auto to_lin_gamut = OCIO_NAMESPACE::MatrixTransform::Create();
209 to_lin_gamut->setMatrix(math::transpose(xyz_to_display_gamut).base_ptr());
210 group->appendTransform(to_lin_gamut);
211
212 if (is_hdr_ || is_data_) {
213 /* Convert linear display gamut to scope space (see above for details). */
214
215 /* Clamp to [0, SCOPE_MAX_LINEAR] and rescale to [0, 1] for the gamma below. */
216 auto clamp = OCIO_NAMESPACE::RangeTransform::Create();
217 clamp->setStyle(OCIO_NAMESPACE::RANGE_CLAMP);
218 clamp->setMinInValue(0.0);
219 clamp->setMinOutValue(0.0);
220 clamp->setMaxInValue(SCOPE_MAX_LINEAR);
221 clamp->setMaxOutValue(1.0);
222 group->appendTransform(clamp);
223
224 /* Apply gamma for better precision with the LUT below. */
225 const double max_gamma_encoded = std::pow(SCOPE_MAX_LINEAR, 1.0 / SCOPE_SRGB_GAMMA);
226 auto gamma = OCIO_NAMESPACE::ExponentTransform::Create();
227 gamma->setValue({1.0 / SCOPE_SRGB_GAMMA, 1.0 / SCOPE_SRGB_GAMMA, 1.0 / SCOPE_SRGB_GAMMA, 1.0});
228 gamma->setNegativeStyle(OCIO_NAMESPACE::NEGATIVE_CLAMP);
229 gamma->setDirection(OCIO_NAMESPACE::TRANSFORM_DIR_FORWARD);
230 group->appendTransform(gamma);
231
232 /* 1D LUT to map gamma to our custom scope space. */
233 constexpr int LUT_SIZE = 1024;
234 auto lut = OCIO_NAMESPACE::Lut1DTransform::Create();
235 lut->setLength(LUT_SIZE);
236 for (int i = 0; i < LUT_SIZE; i++) {
237 const float t = float(i) / float(LUT_SIZE - 1);
238 const float g = t * max_gamma_encoded;
239 const float nits = std::pow(g, SCOPE_SRGB_GAMMA) * SCOPE_SDR_WHITE_NITS;
240 const float scope = nits_to_scope_value(nits);
241 lut->setValue(i, scope, scope, scope);
242 }
243 group->appendTransform(lut);
244 }
245 else {
246 /* SDR Display: clamp and sRGB OETF. */
247 auto clamp = OCIO_NAMESPACE::RangeTransform::Create();
248 clamp->setStyle(OCIO_NAMESPACE::RANGE_CLAMP);
249 clamp->setMinInValue(0.0);
250 clamp->setMinOutValue(0.0);
251 group->appendTransform(clamp);
252
253 auto srgb = OCIO_NAMESPACE::ExponentWithLinearTransform::Create();
254 srgb->setGamma({SCOPE_SRGB_GAMMA, SCOPE_SRGB_GAMMA, SCOPE_SRGB_GAMMA, 1.0});
255 srgb->setOffset({SCOPE_SRGB_B, SCOPE_SRGB_B, SCOPE_SRGB_B, 0.0});
256 srgb->setDirection(OCIO_NAMESPACE::TRANSFORM_DIR_INVERSE);
257 group->appendTransform(srgb);
258 }
259}
260
261} // namespace blender::ocio
#define SNPRINTF(dst, format,...)
volatile int lock
constexpr const char * c_str() const
bool contains(const T &value) const
void append(const T &value)
int max_nits() const override
const ScopeInfo & scope_info() const override
void append_scope_space_transforms(OCIO_NAMESPACE::GroupTransformRcPtr &group, StringRefNull lin_cie_xyz_d65_name) const
constexpr T clamp(T, U, U) RET
MatBase< T, NumCol, NumRow > transpose(const MatBase< T, NumRow, NumCol > &mat)
CartesianBasis invert(const CartesianBasis &basis)
static constexpr float SCOPE_MAX_LINEAR
static constexpr float SCOPE_HDR_MAX_NITS
static constexpr float SCOPE_HDR_D
static constexpr float SCOPE_HDR_B
static constexpr float SCOPE_SRGB_B
static constexpr float SCOPE_HDR_C
static constexpr float SCOPE_SDR_WHITE_NITS
static float linear_to_srgb(const float linear)
static constexpr float SCOPE_SDR_IN_HDR_SCOPE
static constexpr float SCOPE_SRGB_GAMMA
static float nits_to_scope_value(const float nits)
static constexpr float SCOPE_SRGB_A
MatBase< float, 3, 3 > float3x3
VecBase< float, 3 > float3
MatBase< double, 4, 4 > double4x4
KERNEL_FEATURE_LIGHT_PASSES KERNEL_FEATURE_PATH_GUIDING float