HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
OpenColorTransforms.h
Go to the documentation of this file.
1 // SPDX-License-Identifier: BSD-3-Clause
2 // Copyright Contributors to the OpenColorIO Project.
3 
4 
5 #ifndef INCLUDED_OCIO_OPENCOLORTRANSFORMS_H
6 #define INCLUDED_OCIO_OPENCOLORTRANSFORMS_H
7 
8 #include <initializer_list>
9 #include <limits>
10 
11 #include "OpenColorTypes.h"
12 
13 #ifndef OCIO_NAMESPACE
14 #error This header cannot be used directly. Use <OpenColorIO/OpenColorIO.h> instead.
15 #endif
16 
17 /**
18  * C++ Transforms
19  * ==============
20  *
21  * Typically only needed when creating and/or manipulating configurations
22  */
23 
24 namespace OCIO_NAMESPACE
25 {
26 
27 
28 
29 /**
30  * The FormatMetadata class is intended to be a generic container to hold metadata from various
31  * file formats.
32  *
33  * This class provides a hierarchical metadata container. A metadata object is similar to an
34  * element in XML. The top level element is named "ROOT" and can't be renamed. Several transforms
35  * have a FormatMetadata.
36  * The root element and all of the sub-elements may contain:
37  * * A name string (e.g. "ROOT", "Description"...). Name can't be empty.
38  * * A value string (e.g. "updated viewing LUT"). Value can be empty.
39  * * A list of attributes (name, value) string pairs (e.g. "version", "1.5"). There are helper
40  * functions to get and set "id" and "name" attributes. Attribute names are unique.
41  * * And a list of child sub-elements, which are also objects implementing FormatMetadata. There
42  * can be several sub-elements with the same name.
43  */
45 {
46 public:
47  virtual const char * getElementName() const noexcept = 0;
48  /// Name has to be a non-empty string. Top-level element can't be renamed. 'ROOT' is reserved.
49  virtual void setElementName(const char *) = 0;
50 
51  virtual const char * getElementValue() const noexcept = 0;
52  virtual void setElementValue(const char *) = 0;
53 
54  virtual int getNumAttributes() const noexcept = 0;
55  /// Get the name of a attribute ("" if attribute does not exist).
56  virtual const char * getAttributeName(int i) const noexcept = 0;
57  /// Get the value of a attribute ("" if attribute does not exist).
58  virtual const char * getAttributeValue(int i) const noexcept = 0;
59  /// Get the value of a attribute of a given name ("" if attribute does not exist).
60  virtual const char * getAttributeValue(const char * name) const noexcept = 0;
61  /**
62  * Add an attribute with a given name and value. If an attribute with the same name already
63  * exists, its value is replaced. Throw if name is NULL or empty.
64  */
65  virtual void addAttribute(const char * name, const char * value) = 0;
66 
67  virtual int getNumChildrenElements() const noexcept = 0;
68  /**
69  * Access a child element.
70  *
71  * \note
72  * Adding siblings might cause a reallocation of the container and thus might make the
73  * reference unusable.
74  * Index i has to be positive and less than getNumChildrenElements() or the function will
75  * throw.
76  */
77  virtual const FormatMetadata & getChildElement(int i) const = 0;
78  virtual FormatMetadata & getChildElement(int i) = 0;
79 
80  /**
81  * Add a child element with a given name and value.
82  *
83  * Name has to be non-empty. Value may be empty, particularly if this element will have
84  * children. Element is added after all existing children. Use
85  * getChildElement(getNumChildrenElements()-1) to access the added element.
86  */
87  virtual void addChildElement(const char * name, const char * value) = 0;
88 
89  /// Remove all children, all attributes and the value.
90  virtual void clear() noexcept = 0;
91 
92  virtual FormatMetadata & operator=(const FormatMetadata & rhs) = 0;
93 
94  /**
95  * Convenience method to easily get/set the 'name' attribute. This corresponds to the
96  * ProcessNode name attribute from a CLF / CTF file or the name key of a transform in the
97  * config YAML.
98  */
99  virtual const char * getName() const noexcept = 0;
100  virtual void setName(const char * name) noexcept = 0;
101  /**
102  * Convenience method to easily get/set the 'id' attribute. This corresponds to the
103  * ProcessNode id attribute from a CLF/CTF file or the ColorCorrection id attribute from a
104  * CC/CCC/CDL file.
105  */
106  virtual const char * getID() const noexcept = 0;
107  virtual void setID(const char * id) noexcept = 0;
108 
109  FormatMetadata(const FormatMetadata & rhs) = delete;
110  /// Do not use (needed only for pybind11).
111  virtual ~FormatMetadata() = default;
112 
113 protected:
114  FormatMetadata() = default;
115 };
116 
117 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const FormatMetadata &);
118 
119 
120 /// Base class for all the transform classes
122 {
123 public:
124  virtual TransformRcPtr createEditableCopy() const = 0;
125 
126  virtual TransformDirection getDirection() const noexcept = 0;
127  /// Note that this only affects the evaluation and not the values stored in the object.
128  virtual void setDirection(TransformDirection dir) noexcept = 0;
129 
130  virtual TransformType getTransformType() const noexcept = 0;
131 
132  /// Will throw if data is not valid.
133  virtual void validate() const;
134 
135  Transform(const Transform &) = delete;
136  Transform & operator= (const Transform &) = delete;
137  /// Do not use (needed only for pybind11).
138  virtual ~Transform() = default;
139 
140 protected:
141  Transform() = default;
142 };
143 
144 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Transform&);
145 
146 
147 
148 /**
149  * Forward direction wraps the 'expanded' range into the
150  * specified, often compressed, range.
151  */
153 {
154 public:
155  static AllocationTransformRcPtr Create();
156 
157  TransformRcPtr createEditableCopy() const override;
158 
159  TransformDirection getDirection() const noexcept override;
160  void setDirection(TransformDirection dir) noexcept override;
161 
163 
164  /// Will throw if data is not valid.
165  void validate() const override;
166 
167  Allocation getAllocation() const;
168  void setAllocation(Allocation allocation);
169 
170  int getNumVars() const;
171  void getVars(float * vars) const;
172  void setVars(int numvars, const float * vars);
173 
174  AllocationTransform & operator= (const AllocationTransform &) = delete;
175  /// Do not use (needed only for pybind11).
176  virtual ~AllocationTransform();
177 
178 private:
181 
182  static void deleter(AllocationTransform * t);
183 
184  class Impl;
185  Impl * m_impl;
186  Impl * getImpl() { return m_impl; }
187  const Impl * getImpl() const { return m_impl; }
188 };
189 
190 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const AllocationTransform&);
191 
192 
193 /**
194  * A built-in transform is similar to a FileTransform, but without the file.
195  * OCIO knows how to build a set of commonly used transforms on-demand, thus avoiding the need
196  * for external files and simplifying config authoring.
197  */
199 {
200 public:
201  static BuiltinTransformRcPtr Create();
202 
204 
205  virtual const char * getStyle() const noexcept = 0;
206  /**
207  * Select an existing built-in transform style from the list accessible
208  * through :cpp:class:`BuiltinTransformRegistry`. The style is the ID string that identifies
209  * which transform to apply.
210  */
211  virtual void setStyle(const char * style) = 0;
212 
213  virtual const char * getDescription() const noexcept = 0;
214 
215  /// Do not use (needed only for pybind11).
216  virtual ~BuiltinTransform() = default;
217 
218 protected:
219  BuiltinTransform() = default;
220 
221 private:
223  BuiltinTransform & operator= (const BuiltinTransform &) = delete;
224 };
225 
226 //
227 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const BuiltinTransform &) noexcept;
228 
229 
230 /**
231  * \brief
232  * An implementation of the ASC Color Decision List (CDL), based on the ASC v1.2
233  * specification.
234  *
235  * **ASC_SOP**
236  *
237  * Slope, offset, power::
238  * out = clamp( (in * slope) + offset ) ^ power
239  *
240  * \note‚Äč
241  * If the config version is 1, negative values are clamped if the power is not 1.0.
242  * For config version 2 and higher, the negative handling is controlled by the CDL style.
243  */
245 {
246 public:
247  static CDLTransformRcPtr Create();
248 
249  /**
250  * \brief Load the CDL from the src .cdl, .cc, or .ccc file.
251  *
252  * \note
253  * The cccid can be the ID of a CDL or the index of the CDL (as string). If cccid is NULL or
254  * empty the first CDL is returned. The cccid is case-sensitive. The src must be an
255  * absolute path reference, no relative directory or envvar resolution is performed. Throws
256  * if file does not contain any CDL or if the specified cccid is not found.
257  */
258  static CDLTransformRcPtr CreateFromFile(const char * src, const char * cccid);
259 
260  /**
261  * \brief Load all of the CDLs in a .cdl or .ccc file into a single GroupTransform.
262  *
263  * \note
264  * This may be useful as a quicker way for applications to check the contents of each of
265  * the CDLs. The src must be an absolute path reference, no relative directory or envvar
266  * resolution is performed.
267  */
268  static GroupTransformRcPtr CreateGroupFromFile(const char * src);
269 
270  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_CDL; }
271 
272  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
273  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
274 
275  virtual bool equals(const CDLTransform & other) const noexcept = 0;
276 
277  virtual CDLStyle getStyle() const = 0;
278  /**
279  * Use CDL_ASC to clamp values to [0,1] per the ASC spec. Use NO_CLAMP to
280  * never clamp values (regardless of whether power is 1.0). The NO_CLAMP option passes
281  * negatives through unchanged (like the NEGATIVE_PASS_THRU style of ExponentTransform).
282  * The default style is CDL_NO_CLAMP.
283  */
284  virtual void setStyle(CDLStyle style) = 0;
285 
286  virtual void getSlope(double * rgb) const = 0;
287  virtual void setSlope(const double * rgb) = 0;
288 
289  virtual void getOffset(double * rgb) const = 0;
290  virtual void setOffset(const double * rgb) = 0;
291 
292  virtual void getPower(double * rgb) const = 0;
293  virtual void setPower(const double * rgb) = 0;
294 
295  virtual void getSOP(double * vec9) const = 0;
296  virtual void setSOP(const double * vec9) = 0;
297 
298  virtual double getSat() const = 0;
299  virtual void setSat(double sat) = 0;
300 
301  /// These are hard-coded, by spec, to r709.
302  virtual void getSatLumaCoefs(double * rgb) const = 0;
303 
304  /**
305  * The get/setID methods are now deprecated. The preferred way of interacting with the ID is
306  * now via the transform's formatMetadata.
307  */
308  virtual const char * getID() const = 0;
309  virtual void setID(const char * id) = 0;
310 
311  /* Get/Set the first Description element under the SOPNode.
312  * Note: These emulate the get/setDescription methods from OCIO v1.
313  *
314  * Use the FormatMetadata interface for access to other Description elements in the CDL.
315  * The Description children of the SOPNode element in the CDL XML are named 'SOPDescription'
316  * in the FormatMetadata. NULL or empty string removes the first SOPDescription element.
317  */
318  virtual const char * getFirstSOPDescription() const = 0;
319  virtual void setFirstSOPDescription(const char * description) = 0;
320 
321  CDLTransform(const CDLTransform &) = delete;
322  CDLTransform & operator= (const CDLTransform &) = delete;
323  /// Do not use (needed only for pybind11).
324  virtual ~CDLTransform() = default;
325 
326 protected:
327  CDLTransform() = default;
328 };
329 
330 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const CDLTransform &);
331 
332 
334 {
335 public:
336  static ColorSpaceTransformRcPtr Create();
337 
338  TransformRcPtr createEditableCopy() const override;
339 
340  TransformDirection getDirection() const noexcept override;
341  void setDirection(TransformDirection dir) noexcept override;
342 
343  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_COLORSPACE; }
344 
345  void validate() const override;
346 
347  const char * getSrc() const;
348  void setSrc(const char * src);
349 
350  const char * getDst() const;
351  void setDst(const char * dst);
352 
353  /// Data color spaces do not get processed when true (which is the default).
354  bool getDataBypass() const noexcept;
355  void setDataBypass(bool enabled) noexcept;
356 
357  ColorSpaceTransform & operator=(const ColorSpaceTransform &) = delete;
358  /// Do not use (needed only for pybind11).
359  virtual ~ColorSpaceTransform();
360 
361 private:
362  ColorSpaceTransform();
363  ColorSpaceTransform(const ColorSpaceTransform &);
364 
365  static void deleter(ColorSpaceTransform * t);
366 
367  class Impl;
368  Impl * m_impl;
369  Impl * getImpl() { return m_impl; }
370  const Impl * getImpl() const { return m_impl; }
371 };
372 
373 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const ColorSpaceTransform &);
374 
375 
376 class OCIOEXPORT DisplayViewTransform : public Transform
377 {
378 public:
379  static DisplayViewTransformRcPtr Create();
380 
381  TransformRcPtr createEditableCopy() const override;
382 
383  TransformDirection getDirection() const noexcept override;
384  void setDirection(TransformDirection dir) noexcept override;
385 
387 
388  /// Will throw if data is not valid.
389  void validate() const override;
390 
391  const char * getSrc() const;
392  /// Specify the incoming color space.
393  void setSrc(const char * name);
394 
395  const char * getDisplay() const;
396  /// Specify which display to use.
397  void setDisplay(const char * display);
398 
399  const char * getView() const;
400  /// Specify which view transform to use.
401  void setView(const char * view);
402 
403  bool getLooksBypass() const;
404  /// Looks will be bypassed when true (the default is false).
405  void setLooksBypass(bool bypass);
406 
407  bool getDataBypass() const noexcept;
408  /// Data color spaces do not get processed when true (which is the default).
409  void setDataBypass(bool bypass) noexcept;
410 
411  /// Do not use (needed only for pybind11).
412  virtual ~DisplayViewTransform();
413 
414 private:
415  DisplayViewTransform();
416  DisplayViewTransform(const DisplayViewTransform &) = delete;
417  DisplayViewTransform & operator=(const DisplayViewTransform &) = delete;
418 
419  static void deleter(DisplayViewTransform * t);
420 
421  class Impl;
422  Impl * m_impl;
423  Impl * getImpl() { return m_impl; }
424  const Impl * getImpl() const { return m_impl; }
425 };
426 
427 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const DisplayViewTransform &);
428 
429 /**
430  * Used by the grading transforms to hold the red, green, blue, and master components
431  * of a single parameter. The master component affects all three channels (RGB).
432  */
434 {
435  GradingRGBM() = default;
436  GradingRGBM(const GradingRGBM &) = default;
437  GradingRGBM(double red, double green, double blue, double master)
438  : m_red(red)
439  , m_green(green)
440  , m_blue(blue)
441  , m_master(master)
442  {
443  }
444  GradingRGBM(const double(&rgbm)[4])
445  : m_red(rgbm[0])
446  , m_green(rgbm[1])
447  , m_blue(rgbm[2])
448  , m_master(rgbm[3])
449  {
450  }
451  double m_red{ 0. };
452  double m_green{ 0. };
453  double m_blue{ 0. };
454  double m_master{ 0. };
455 };
456 
457 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingRGBM &);
458 
459 /// Grading primary values.
461 {
462  GradingPrimary() = delete;
463  GradingPrimary(const GradingPrimary &) = default;
464  explicit GradingPrimary(GradingStyle style)
465  : m_pivot(style == GRADING_LOG ? -0.2 : 0.18)
466  , m_clampBlack(NoClampBlack())
467  , m_clampWhite(NoClampWhite())
468  {
469  }
470 
471  GradingRGBM m_brightness{ 0.0, 0.0, 0.0, 0.0 };
472  GradingRGBM m_contrast { 1.0, 1.0, 1.0, 1.0 };
473  GradingRGBM m_gamma { 1.0, 1.0, 1.0, 1.0 };
474  GradingRGBM m_offset { 0.0, 0.0, 0.0, 0.0 };
475  GradingRGBM m_exposure { 0.0, 0.0, 0.0, 0.0 };
476  GradingRGBM m_lift { 0.0, 0.0, 0.0, 0.0 };
477  GradingRGBM m_gain { 1.0, 1.0, 1.0, 1.0 };
478 
479  double m_saturation{ 1.0 };
480  double m_pivot; // For LOG default is -0.2. LIN default is 0.18.
481  double m_pivotBlack{ 0.0 };
482  double m_pivotWhite{ 1.0 };
483  double m_clampBlack;
484  double m_clampWhite;
485 
486  /// The valid range for each parameter varies.
487  void validate(GradingStyle style) const;
488 
489  static double NoClampBlack();
490  static double NoClampWhite();
491 };
492 
493 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingPrimary &);
494 
495 /// 2D control point used by \ref GradingBSplineCurve.
497 {
498  GradingControlPoint() = default;
499  GradingControlPoint(const GradingControlPoint &) = default;
500  GradingControlPoint(float x, float y) : m_x(x), m_y(y) {}
501  float m_x{ 0.f };
502  float m_y{ 0.f };
503 };
504 
505 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingControlPoint &);
506 
507 /// A BSpline curve defined with \ref GradingControlPoint.
509 {
510 public:
511  /// Create a BSpline curve with a specified number of control points.
512  static GradingBSplineCurveRcPtr Create(size_t size);
513  /// Create a BSpline curve with a list of control points.
514  static GradingBSplineCurveRcPtr Create(std::initializer_list<GradingControlPoint> values);
515 
516  virtual GradingBSplineCurveRcPtr createEditableCopy() const = 0;
517  virtual size_t getNumControlPoints() const noexcept = 0;
518  virtual void setNumControlPoints(size_t size) = 0;
519  virtual const GradingControlPoint & getControlPoint(size_t index) const = 0;
520  virtual GradingControlPoint & getControlPoint(size_t index) = 0;
521  virtual float getSlope(size_t index) const = 0;
522  virtual void setSlope(size_t index, float slope) = 0;
523  virtual bool slopesAreDefault() const = 0;
524  virtual void validate() const = 0;
525 
526  GradingBSplineCurve(const GradingBSplineCurve &) = delete;
527  GradingBSplineCurve & operator= (const GradingBSplineCurve &) = delete;
528 
529  /// Do not use (needed only for pybind11).
530  virtual ~GradingBSplineCurve() = default;
531 
532 protected:
533  GradingBSplineCurve() = default;
534 };
535 
536 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingBSplineCurve &);
537 
538 /**
539  * A set of red, green, blue and master curves. It is used by RGBCurveTransform and can be used as
540  * a dynamic property (see \ref DynamicPropertyGradingRGBCurve).
541  */
543 {
544 public:
545  static GradingRGBCurveRcPtr Create(GradingStyle style);
546  static GradingRGBCurveRcPtr Create(const ConstGradingRGBCurveRcPtr & rhs);
550  const ConstGradingBSplineCurveRcPtr & master);
551 
552  virtual GradingRGBCurveRcPtr createEditableCopy() const = 0;
553  virtual void validate() const = 0;
554  virtual bool isIdentity() const = 0;
555  virtual ConstGradingBSplineCurveRcPtr getCurve(RGBCurveType c) const = 0;
556  virtual GradingBSplineCurveRcPtr getCurve(RGBCurveType c) = 0;
557 
558  /// Do not use (needed only for pybind11).
559  virtual ~GradingRGBCurve() = default;
560 
561 protected:
562  GradingRGBCurve() = default;
563 };
564 
565 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingRGBCurve &);
566 
567 /**
568  * Used by the grading tone transforms to hold the red, green, blue, master, start,
569  * and width components of a single parameter. The master component affects all three channels
570  * (RGB). The start and width components control the range of tones affected. Although this
571  * struct simply uses "start" and "width" for all the range values, the actual user-facing name
572  * changes based on the parameter.
573  */
575 {
576  GradingRGBMSW() = default;
577  GradingRGBMSW(const GradingRGBMSW &) = default;
578  GradingRGBMSW(double red, double green, double blue, double master, double start, double width)
579  : m_red (red)
580  , m_green (green)
581  , m_blue (blue)
582  , m_master(master)
583  , m_start (start)
584  , m_width (width)
585  {
586  }
587  GradingRGBMSW(const double(&rgbmsw)[6])
588  : m_red (rgbmsw[0])
589  , m_green (rgbmsw[1])
590  , m_blue (rgbmsw[2])
591  , m_master(rgbmsw[3])
592  , m_start (rgbmsw[4])
593  , m_width (rgbmsw[5])
594  {
595  }
596  GradingRGBMSW(double start, double width)
597  : m_start(start)
598  , m_width(width)
599  {
600  }
601  double m_red { 1. };
602  double m_green { 1. };
603  double m_blue { 1. };
604  double m_master{ 1. };
605  double m_start { 0. }; // Or center for midtones.
606  double m_width { 1. }; // Or pivot for shadows and highlights.
607 };
608 
609 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingRGBMSW &);
610 
611 /// Grading tone values.
613 {
614  GradingTone() = delete;
615  GradingTone(const GradingTone &) = default;
616  explicit GradingTone(GradingStyle style)
617  : m_blacks(style == GRADING_LIN ? GradingRGBMSW(0., 4.) :
618  (style == GRADING_LOG ? GradingRGBMSW(0.4, 0.4) :
619  GradingRGBMSW(0.4, 0.4)))
620  , m_shadows(style == GRADING_LIN ? GradingRGBMSW(2., -7.) :
621  (style == GRADING_LOG ? GradingRGBMSW(0.5, 0.) :
622  GradingRGBMSW(0.6, 0.)))
623  , m_midtones(style == GRADING_LIN ? GradingRGBMSW(0., 8.) :
624  (style == GRADING_LOG ? GradingRGBMSW(0.4, 0.6) :
625  GradingRGBMSW(0.4, 0.7)))
626  , m_highlights(style == GRADING_LIN ? GradingRGBMSW(-2., 9.) :
627  (style == GRADING_LOG ? GradingRGBMSW(0.3, 1.) :
628  GradingRGBMSW(0.2, 1.)))
629  , m_whites(style == GRADING_LIN ? GradingRGBMSW(0., 8.) :
630  (style == GRADING_LOG ? GradingRGBMSW(0.4, 0.5) :
631  GradingRGBMSW(0.5, 0.5)))
632  {
633  }
634 
635  /**
636  * The valid range for each parameter varies. The client is expected to enforce
637  * these bounds in the UI.
638  */
639  void validate() const;
640 
646  double m_scontrast{ 1.0 };
647 };
648 
649 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingTone &);
650 
651 /**
652  * Allows transform parameter values to be set on-the-fly (after finalization). For
653  * example, to modify the exposure in a viewport. Dynamic properties can be accessed from the
654  * `CPUProcessor` or `GpuShaderCreator` to change values between processing.
655  *
656  * \code{.cpp}
657  *
658  * OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig();
659  * OCIO::ConstProcessorRcPtr processor = config->getProcessor(colorSpace1, colorSpace2);
660  * OCIO::ConstCPUProcessorRcPtr cpuProcessor = processor->getDefaultCPUProcessor();
661  *
662  * if (cpuProcessor->hasDynamicProperty(OCIO::DYNAMIC_PROPERTY_EXPOSURE))
663  * {
664  * // Get the in-memory implementation of the dynamic property.
665  * OCIO::DynamicPropertyRcPtr dynProp =
666  * cpuProcessor->getDynamicProperty(OCIO::DYNAMIC_PROPERTY_EXPOSURE);
667  * // Get the interface used to change the double value.
668  * OCIO::DynamicPropertyDoubleRcPtr exposure =
669  * OCIO::DynamicPropertyValue::AsDouble(dynProp);
670  * // Update of the dynamic property instance with the new value.
671  * exposure->setValue(1.1f);
672  * }
673  * if (cpuProcessor->hasDynamicProperty(OCIO::DYNAMIC_PROPERTY_GRADING_PRIMARY))
674  * {
675  * OCIO::DynamicPropertyRcPtr dynProp =
676  * cpuProcessor->getDynamicProperty(OCIO::DYNAMIC_PROPERTY_GRADING_PRIMARY);
677  * OCIO::DynamicPropertyGradingPrimaryRcPtr primaryProp =
678  * OCIO::DynamicPropertyValue::AsGradingPrimary(dynProp);
679  * OCIO::GradingPrimary primary = primaryProp->getValue();
680  * primary.m_saturation += 0.1f;
681  * rgbCurveProp->setValue(primary);
682  * }
683  * if (cpuProcessor->hasDynamicProperty(OCIO::DYNAMIC_PROPERTY_GRADING_RGBCURVE))
684  * {
685  * OCIO::DynamicPropertyRcPtr dynProp =
686  * cpuProcessor->getDynamicProperty(OCIO::DYNAMIC_PROPERTY_GRADING_RGBCURVE);
687  * OCIO::DynamicPropertyGradingRGBCurveRcPtr rgbCurveProp =
688  * OCIO::DynamicPropertyValue::AsGradingRGBCurve(dynProp);
689  * OCIO::ConstGradingRGBCurveRcPtr rgbCurve = rgbCurveProp->getValue()->createEditableCopy();
690  * OCIO::GradingBSplineCurveRcPtr rCurve = rgbCurve->getCurve(OCIO::RGB_RED);
691  * rCurve->getControlPoint(1).m_y += 0.1f;
692  * rgbCurveProp->setValue(rgbCurve);
693  * }
694  * \endcode
695  */
697 {
698 public:
699  virtual DynamicPropertyType getType() const noexcept = 0;
700 
701  DynamicProperty & operator=(const DynamicProperty &) = delete;
702  DynamicProperty(const DynamicProperty &) = delete;
703 
704  /// Do not use (needed only for pybind11).
705  virtual ~DynamicProperty() = default;
706 
707 protected:
708  DynamicProperty() = default;
709 };
710 
711 namespace DynamicPropertyValue
712 {
713 /**
714  * Get the property as DynamicPropertyDoubleRcPtr to access the double value. Will throw if
715  * property type is not a type that holds a double such as DYNAMIC_PROPERTY_EXPOSURE.
716  */
718 /**
719  * Get the property as DynamicPropertyGradingPrimaryRcPtr to access the GradingPrimary value. Will
720  * throw if property type is not DYNAMIC_PROPERTY_GRADING_PRIMARY.
721  */
723 /**
724  * Get the property as DynamicPropertyGradingRGBCurveRcPtr to access the GradingRGBCurveRcPtr
725  * value. Will throw if property type is not DYNAMIC_PROPERTY_GRADING_RGBCURVE.
726  */
728 /**
729  * Get the property as DynamicPropertyGradingToneRcPtr to access the GradingTone value. Will throw
730  * if property type is not DYNAMIC_PROPERTY_GRADING_TONE.
731  */
733 }
734 
735 /// Interface used to access dynamic property double value.
737 {
738 public:
739  virtual double getValue() const = 0;
740  virtual void setValue(double value) = 0;
741 
743  DynamicPropertyDouble & operator=(const DynamicPropertyDouble &) = delete;
744  /// Do not use (needed only for pybind11).
745  virtual ~DynamicPropertyDouble() = default;
746 
747 protected:
748  DynamicPropertyDouble() = default;
749 };
750 
751 /// Interface used to access dynamic property GradingPrimary value.
753 {
754 public:
755  virtual const GradingPrimary & getValue() const = 0;
756  /// Will throw if value is not valid.
757  virtual void setValue(const GradingPrimary & value) = 0;
758 
760  DynamicPropertyGradingPrimary & operator=(const DynamicPropertyGradingPrimary &) = delete;
761  /// Do not use (needed only for pybind11).
762  virtual ~DynamicPropertyGradingPrimary() = default;
763 
764 protected:
765  DynamicPropertyGradingPrimary() = default;
766 };
767 
768 /// Interface used to access dynamic property ConstGradingRGBCurveRcPtr value.
770 {
771 public:
772  virtual const ConstGradingRGBCurveRcPtr & getValue() const = 0;
773  /// Will throw if value is not valid.
774  virtual void setValue(const ConstGradingRGBCurveRcPtr & value) = 0;
775 
778  /// Do not use (needed only for pybind11).
779  virtual ~DynamicPropertyGradingRGBCurve() = default;
780 
781 protected:
782  DynamicPropertyGradingRGBCurve() = default;
783 };
784 
785 /// Interface used to access dynamic property GradingTone value.
787 {
788 public:
789  virtual const GradingTone & getValue() const = 0;
790  /// Will throw if value is not valid.
791  virtual void setValue(const GradingTone & value) = 0;
792 
794  DynamicPropertyGradingTone & operator=(const DynamicPropertyGradingTone &) = delete;
795  /// Do not use (needed only for pybind11).
796  virtual ~DynamicPropertyGradingTone() = default;
797 
798 protected:
799  DynamicPropertyGradingTone() = default;
800 };
801 
802 
803 /**
804  * \brief Represents exponent transform: pow( clamp(color), value ).
805  *
806  * \note For configs with version == 1: Negative style is ignored and if the exponent is 1.0,
807  * this will not clamp. Otherwise, the input color will be clamped between [0.0, inf].
808  * For configs with version > 1: Negative value handling may be specified via setNegativeStyle.
809  */
810 class OCIOEXPORT ExponentTransform : public Transform
811 {
812 public:
813  static ExponentTransformRcPtr Create();
814 
816 
817  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
818  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
819 
820  /// Checks if this exactly equals other.
821  virtual bool equals(const ExponentTransform & other) const noexcept = 0;
822 
823  virtual void getValue(double(&vec4)[4]) const noexcept = 0;
824  virtual void setValue(const double(&vec4)[4]) noexcept = 0;
825 
826  /**
827  * Specifies how negative values are handled. Legal values:
828  *
829  * * NEGATIVE_CLAMP -- Clamp negative values (default).
830  * * NEGATIVE_MIRROR -- Positive curve is rotated 180 degrees around the origin to
831  * handle negatives.
832  * * NEGATIVE_PASS_THRU -- Negative values are passed through unchanged.
833  */
834  virtual NegativeStyle getNegativeStyle() const = 0;
835  virtual void setNegativeStyle(NegativeStyle style) = 0;
836 
837  ExponentTransform(const ExponentTransform &) = delete;
838  ExponentTransform & operator= (const ExponentTransform &) = delete;
839  /// Do not use (needed only for pybind11).
840  virtual ~ExponentTransform() = default;
841 
842 protected:
843  ExponentTransform() = default;
844 };
845 
846 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const ExponentTransform &);
847 
848 
849 /**
850  * Represents power functions with a linear section in the shadows
851  * such as sRGB and L*.
852  *
853  * The basic formula is::
854  *
855  * pow( (x + offset)/(1 + offset), gamma )
856  * with the breakpoint at offset/(gamma - 1).
857  *
858  * Negative values are never clamped.
859  */
861 {
862 public:
863  static ExponentWithLinearTransformRcPtr Create();
864 
866 
867  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
868  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
869 
870  /// Checks if this exactly equals other.
871  virtual bool equals(const ExponentWithLinearTransform & other) const noexcept = 0;
872 
873  virtual void getGamma(double(&values)[4]) const noexcept = 0;
874  /**
875  * Set the exponent value for the power function for R, G, B, A.
876  *
877  * \note
878  * The gamma values must be in the range of [1, 10]. Set the transform direction
879  * to inverse to obtain the effect of values less than 1.
880  */
881  virtual void setGamma(const double(&values)[4]) noexcept = 0;
882 
883  virtual void getOffset(double(&values)[4]) const noexcept = 0;
884  /**
885  * Set the offset value for the power function for R, G, B, A.
886  *
887  * \note
888  * The offset values must be in the range [0, 0.9].
889  */
890  virtual void setOffset(const double(&values)[4]) noexcept = 0;
891 
892  /**
893  * Specifies how negative values are handled. Legal values:
894  *
895  * * NEGATIVE_LINEAR -- Linear segment continues into negatives (default).
896  * * NEGATIVE_MIRROR -- Positive curve is rotated 180 degrees around the origin to
897  * handle negatives.
898  */
899  virtual NegativeStyle getNegativeStyle() const = 0;
900  virtual void setNegativeStyle(NegativeStyle style) = 0;
901 
903  ExponentWithLinearTransform & operator= (const ExponentWithLinearTransform &) = delete;
904  /// Do not use (needed only for pybind11).
905  virtual ~ExponentWithLinearTransform() = default;
906 
907 protected:
908  ExponentWithLinearTransform() = default;
909 };
910 
911 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const ExponentWithLinearTransform &);
912 
913 /**
914  * Applies exposure, gamma, and pivoted contrast adjustments.
915  * Adjusts the math to be appropriate for linear, logarithmic, or video
916  * color spaces.
917  */
919 {
920 public:
921  static ExposureContrastTransformRcPtr Create();
922 
924 
925  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
926  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
927 
928  /// Checks if this exactly equals other.
929  virtual bool equals(const ExposureContrastTransform & other) const noexcept = 0;
930 
931  virtual ExposureContrastStyle getStyle() const = 0;
932  /// Select the algorithm for linear, video or log color spaces.
933  virtual void setStyle(ExposureContrastStyle style) = 0;
934 
935  virtual double getExposure() const = 0;
936  /**
937  * Applies an exposure adjustment. The value is in units of stops (regardless of style), for
938  * example, a value of -1 would be equivalent to reducing the lighting by one half.
939  */
940  virtual void setExposure(double exposure) = 0;
941  /**
942  * Exposure can be made dynamic so the value can be changed through the CPU or GPU processor,
943  * but if there are several ExposureContrastTransform only one can have a dynamic exposure.
944  */
945  virtual bool isExposureDynamic() const = 0;
946  virtual void makeExposureDynamic() = 0;
947  virtual void makeExposureNonDynamic() = 0;
948 
949  virtual double getContrast() const = 0;
950  /**
951  * Applies a contrast/gamma adjustment around a pivot point. The contrast and gamma are
952  * mathematically the same, but two controls are provided to enable the use of separate
953  * dynamic parameters. Contrast is usually a scene-referred adjustment that pivots around
954  * gray whereas gamma is usually a display-referred adjustment that pivots around white.
955  */
956  virtual void setContrast(double contrast) = 0;
957  /**
958  * Contrast can be made dynamic so the value can be changed through the CPU or GPU processor,
959  * but if there are several ExposureContrastTransform only one can have a dynamic contrast.
960  */
961  virtual bool isContrastDynamic() const = 0;
962  virtual void makeContrastDynamic() = 0;
963  virtual void makeContrastNonDynamic() = 0;
964 
965  virtual double getGamma() const = 0;
966  virtual void setGamma(double gamma) = 0;
967  /**
968  * Gamma can be made dynamic so the value can be changed through the CPU or GPU processor,
969  * but if there are several ExposureContrastTransform only one can have a dynamic gamma.
970  */
971  virtual bool isGammaDynamic() const = 0;
972  virtual void makeGammaDynamic() = 0;
973  virtual void makeGammaNonDynamic() = 0;
974 
975  virtual double getPivot() const = 0;
976  /**
977  * Set the pivot point around which the contrast
978  * and gamma controls will work. Regardless of whether
979  * linear/video/log-style is being used, the pivot is always expressed
980  * in linear. In other words, a pivot of 0.18 is always mid-gray.
981  */
982  virtual void setPivot(double pivot) = 0;
983 
984  virtual double getLogExposureStep() const = 0;
985  /**
986  * Set the increment needed to move one stop for
987  * the log-style algorithm. For example, ACEScct is 0.057, LogC is
988  * roughly 0.074, and Cineon is roughly 90/1023 = 0.088.
989  * The default value is 0.088.
990  */
991  virtual void setLogExposureStep(double logExposureStep) = 0;
992 
993  virtual double getLogMidGray() const = 0;
994  /**
995  * Set the position of 18% gray for use by the
996  * log-style algorithm. For example, ACEScct is about 0.41, LogC is
997  * about 0.39, and ADX10 is 445/1023 = 0.435.
998  * The default value is 0.435.
999  */
1000  virtual void setLogMidGray(double logMidGray) = 0;
1001 
1002  /// Do not use (needed only for pybind11).
1003  virtual ~ExposureContrastTransform() = default;
1004 
1005 protected:
1006  ExposureContrastTransform() = default;
1007 
1008 private:
1010  ExposureContrastTransform & operator= (const ExposureContrastTransform &) = delete;
1011 };
1012 
1013 extern OCIOEXPORT std::ostream & operator<<(std::ostream &,
1014  const ExposureContrastTransform &);
1015 
1016 
1017 class OCIOEXPORT FileTransform : public Transform
1018 {
1019 public:
1020  static FileTransformRcPtr Create();
1021 
1022  TransformRcPtr createEditableCopy() const override;
1023 
1024  TransformDirection getDirection() const noexcept override;
1025  void setDirection(TransformDirection dir) noexcept override;
1026 
1027  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_FILE; }
1028 
1029  /// Will throw if data is not valid.
1030  void validate() const override;
1031 
1032  const char * getSrc() const;
1033  void setSrc(const char * src);
1034 
1035  /**
1036  * The cccid can be the ID of a CDL or the index of the CDL (as string). If cccid is NULL or
1037  * empty the first CDL is returned. The cccid is case-sensitive.
1038  */
1039  const char * getCCCId() const;
1040  void setCCCId(const char * id);
1041 
1042  CDLStyle getCDLStyle() const;
1043  /**
1044  * Can be used with CDL, CC & CCC formats to specify the clamping behavior of
1045  * the CDLTransform. Default is CDL_NO_CLAMP.
1046  */
1047  void setCDLStyle(CDLStyle);
1048 
1049  /**
1050  * The file parsers that care about interpolation (LUTs) will try to make use of the requested
1051  * interpolation method when loading the file. In these cases, if the requested method could
1052  * not be used, a warning is logged. If no method is provided, or a method cannot be used,
1053  * INTERP_DEFAULT is used.
1054  */
1055  Interpolation getInterpolation() const;
1056  void setInterpolation(Interpolation interp);
1057 
1058  /// Get the number of LUT readers.
1059  static int GetNumFormats();
1060  /// Get the LUT readers at index, return empty string if an invalid index is specified.
1061  static const char * GetFormatNameByIndex(int index);
1062  /// Get the LUT reader extension at index, return empty string if an invalid index is specified.
1063  static const char * GetFormatExtensionByIndex(int index);
1064 
1065  FileTransform & operator=(const FileTransform &) = delete;
1066  /// Do not use (needed only for pybind11).
1067  virtual ~FileTransform();
1068 
1069 private:
1070  FileTransform();
1071  FileTransform(const FileTransform &);
1072 
1073  static void deleter(FileTransform * t);
1074 
1075  class Impl;
1076  Impl * m_impl;
1077  Impl * getImpl() { return m_impl; }
1078  const Impl * getImpl() const { return m_impl; }
1079 };
1080 
1081 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const FileTransform &);
1082 
1083 
1084 /**
1085  * Provides a set of hard-coded algorithmic building blocks
1086  * that are needed to accurately implement various common color transformations.
1087  */
1088 class OCIOEXPORT FixedFunctionTransform : public Transform
1089 {
1090 public:
1091  static FixedFunctionTransformRcPtr Create(FixedFunctionStyle style);
1092  static FixedFunctionTransformRcPtr Create(FixedFunctionStyle style,
1093  const double * params,
1094  size_t num);
1095 
1096  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_FIXED_FUNCTION; }
1097 
1098  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1099  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1100 
1101  /// Checks if this exactly equals other.
1102  virtual bool equals(const FixedFunctionTransform & other) const noexcept = 0;
1103 
1104  virtual FixedFunctionStyle getStyle() const = 0;
1105  /// Select which algorithm to use.
1106  virtual void setStyle(FixedFunctionStyle style) = 0;
1107 
1108  virtual size_t getNumParams() const = 0;
1109  virtual void getParams(double * params) const = 0;
1110  /// Set the parameters (for functions that require them).
1111  virtual void setParams(const double * params, size_t num) = 0;
1112 
1114  FixedFunctionTransform & operator= (const FixedFunctionTransform &) = delete;
1115  /// Do not use (needed only for pybind11).
1116  virtual ~FixedFunctionTransform() = default;
1117 
1118 protected:
1119  FixedFunctionTransform() = default;
1120 };
1121 
1122 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const FixedFunctionTransform &);
1123 
1124 
1125 /**
1126  * Primary color correction controls.
1127  *
1128  * This transform is for making basic color correction adjustments to an image such as brightness,
1129  * contrast, or saturation.
1130  *
1131  * The controls are customized for linear, logarithmic, and video color encodings.
1132  * * Linear controls: Exposure, Contrast, Pivot, Offset, Saturation, Black Clip, White Clip.
1133  * * Log controls: Brightness, Contrast, Pivot, Log Gamma, Saturation, Black Clip, White Clip,
1134  * Black Pivot White Pivot.
1135  * * Video controls : Lift, Gamma, Gain, Offset, Saturation, Black Clip, White Clip,
1136  * Black Pivot White Pivot.
1137  *
1138  * The controls are dynamic, so they may be adjusted even after the Transform has been included
1139  * in a Processor.
1140  */
1142 {
1143 public:
1144  /// Creates an instance of GradingPrimaryTransform.
1145  static GradingPrimaryTransformRcPtr Create(GradingStyle style);
1146 
1147  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_GRADING_PRIMARY; }
1148 
1149  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1150  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1151 
1152  /// Checks if this equals other.
1153  virtual bool equals(const GradingPrimaryTransform & other) const noexcept = 0;
1154 
1155  /// Adjusts the behavior of the transform for log, linear, or video color space encodings.
1156  virtual GradingStyle getStyle() const noexcept = 0;
1157  /// Will reset value to style's defaults if style is not the current style.
1158  virtual void setStyle(GradingStyle style) noexcept = 0;
1159 
1160  virtual const GradingPrimary & getValue() const = 0;
1161  /// Throws if value is not valid.
1162  virtual void setValue(const GradingPrimary & values) = 0;
1163 
1164  /**
1165  * Parameters can be made dynamic so the values can be changed through the CPU or GPU processor,
1166  * but if there are several GradingPrimaryTransform only one can have dynamic parameters.
1167  */
1168  virtual bool isDynamic() const noexcept = 0;
1169  virtual void makeDynamic() noexcept = 0;
1170  virtual void makeNonDynamic() noexcept = 0;
1171 
1173  GradingPrimaryTransform & operator= (const GradingPrimaryTransform &) = delete;
1174  /// Do not use (needed only for pybind11).
1175  virtual ~GradingPrimaryTransform() = default;
1176 
1177 protected:
1178  GradingPrimaryTransform() = default;
1179 };
1180 
1181 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingPrimaryTransform &) noexcept;
1182 
1183 
1184 /**
1185  * RGB curve color correction controls.
1186  *
1187  * This transform allows for modifying tone reproduction via B-spline curves.
1188  *
1189  * There is an R, G, and B curve along with a Master curve (that applies to R, G, and B). Each
1190  * curve is specified via the x and y coordinates of its control points. A monotonic spline is
1191  * fit to the control points. The x coordinates must be non-decreasing. When the grading style
1192  * is linear, the units for the control points are photographic stops relative to 0.18.
1193  *
1194  * The control points are dynamic, so they may be adjusted even after the Transform is included
1195  * in a Processor.
1196  */
1198 {
1199 public:
1200  /// Creates an instance of GradingPrimaryTransform.
1201  static GradingRGBCurveTransformRcPtr Create(GradingStyle style);
1202 
1204 
1205  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1206  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1207 
1208  /// Checks if this equals other.
1209  virtual bool equals(const GradingRGBCurveTransform & other) const noexcept = 0;
1210 
1211  /// Adjusts the behavior of the transform for log, linear, or video color space encodings.
1212  virtual GradingStyle getStyle() const noexcept = 0;
1213  /// Will reset value to style's defaults if style is not the current style.
1214  virtual void setStyle(GradingStyle style) noexcept = 0;
1215 
1216  virtual const ConstGradingRGBCurveRcPtr getValue() const = 0;
1217  /// Throws if value is not valid.
1218  virtual void setValue(const ConstGradingRGBCurveRcPtr & values) = 0;
1219 
1220  /**
1221  * It is possible to provide a desired slope value for each control point. The number of slopes is
1222  * always the same as the number of control points and so the control points must be set before
1223  * setting the slopes. The slopes are primarily intended for use by config authors looking to match
1224  * a specific shape with as few control points as possible, they are not intended to be exposed to
1225  * a user interface for direct manipulation. When a curve is being generated for creative purposes
1226  * it is better to let OCIO calculate the slopes automatically.
1227  */
1228  virtual float getSlope(RGBCurveType c, size_t index) const = 0;
1229  virtual void setSlope(RGBCurveType c, size_t index, float slope) = 0;
1230  virtual bool slopesAreDefault(RGBCurveType c) const = 0;
1231 
1232  /**
1233  * The scene-linear grading style applies a lin-to-log transform to the pixel
1234  * values before going through the curve. However, in some cases (e.g. drawing curves in a UI)
1235  * it may be useful to bypass the lin-to-log. Default value is false.
1236  */
1237  virtual bool getBypassLinToLog() const = 0;
1238  virtual void setBypassLinToLog(bool bypass) = 0;
1239 
1240  /**
1241  * Parameters can be made dynamic so the values can be changed through the CPU or GPU processor,
1242  * but if there are several GradingRGBCurveTransform only one can have dynamic parameters.
1243  */
1244  virtual bool isDynamic() const noexcept = 0;
1245  virtual void makeDynamic() noexcept = 0;
1246  virtual void makeNonDynamic() noexcept = 0;
1247 
1249  GradingRGBCurveTransform & operator= (const GradingRGBCurveTransform &) = delete;
1250  /// Do not use (needed only for pybind11).
1251  virtual ~GradingRGBCurveTransform() = default;
1252 
1253 protected:
1254  GradingRGBCurveTransform() = default;
1255 };
1256 
1257 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingRGBCurveTransform &) noexcept;
1258 
1259 
1260 /**
1261  * Tonal color correction controls.
1262  *
1263  * This transform is for making fine adjustments to tone reproduction in specific tonal ranges.
1264  *
1265  * There are five tonal controls and each one has two parameters to control its range:
1266  * * Blacks (start, width)
1267  * * Shadows(start, pivot)
1268  * * Midtones(center, width)
1269  * * Highlights(start, pivot)
1270  * * Whites(start, width)
1271  *
1272  * The transform has three styles that adjust the response and default ranges for linear,
1273  * logarithimic, and video color encodings. The defaults vary based on the style. When the
1274  * style is linear, the units for start/width/etc. are photographic stops relative to 0.18.
1275  *
1276  * Each control allows R, G, B adjustments and a Master adjustment.
1277  *
1278  * There is also an S-contrast control for imparting an S-shape curve.
1279  *
1280  * The controls are dynamic, so they may be adjusted even after the Transform has been included
1281  * in a Processor.
1282  */
1284 {
1285 public:
1286  /// Creates an instance of GradingToneTransform.
1287  static GradingToneTransformRcPtr Create(GradingStyle style);
1288 
1289  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_GRADING_TONE; }
1290 
1291  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1292  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1293 
1294  virtual bool equals(const GradingToneTransform & other) const noexcept = 0;
1295 
1296  /// Adjusts the behavior of the transform for log, linear, or video color space encodings.
1297  virtual GradingStyle getStyle() const noexcept = 0;
1298  /// Will reset value to style's defaults if style is not the current style.
1299  virtual void setStyle(GradingStyle style) noexcept = 0;
1300 
1301  virtual const GradingTone & getValue() const = 0;
1302  virtual void setValue(const GradingTone & values) = 0;
1303 
1304  /**
1305  * Parameters can be made dynamic so the values can be changed through the CPU or GPU processor,
1306  * but if there are several GradingToneTransform only one can have dynamic parameters.
1307  */
1308  virtual bool isDynamic() const noexcept = 0;
1309  virtual void makeDynamic() noexcept = 0;
1310  virtual void makeNonDynamic() noexcept = 0;
1311 
1312  GradingToneTransform(const GradingToneTransform &) = delete;
1313  GradingToneTransform & operator= (const GradingToneTransform &) = delete;
1314  /// Do not use (needed only for pybind11).
1315  virtual ~GradingToneTransform() = default;
1316 
1317 protected:
1318  GradingToneTransform() = default;
1319 };
1320 
1321 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GradingToneTransform &) noexcept;
1322 
1323 
1324 class OCIOEXPORT GroupTransform : public Transform
1325 {
1326 public:
1327  static GroupTransformRcPtr Create();
1328 
1329  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1330  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1331 
1332  /// Throws if index is not allowed.
1333  virtual ConstTransformRcPtr getTransform(int index) const = 0;
1334 
1335  /// Throws if index is not allowed.
1336  virtual TransformRcPtr & getTransform(int index) = 0;
1337 
1338  /// Return number of transforms.
1339  virtual int getNumTransforms() const noexcept = 0;
1340  /// Adds a transform to the end of the group.
1341  virtual void appendTransform(TransformRcPtr transform) noexcept = 0;
1342  /// Add a transform at the beginning of the group.
1343  virtual void prependTransform(TransformRcPtr transform) noexcept = 0;
1344 
1345  /**
1346  * \brief Write the transforms comprising the group to the stream.
1347  *
1348  * Writing (as opposed to Baking) is a lossless process. An exception is thrown if the
1349  * processor cannot be losslessly written to the specified file format. Transforms such as
1350  * FileTransform or ColorSpaceTransform are resolved into write-able simple transforms using
1351  * the config and context. Supported formats include CTF, CLF, and CDL. All available formats
1352  * can be listed with the following:
1353  * \code{.cpp}
1354  * // What are the allowed writing output formats?
1355  * std::ostringstream formats;
1356  * formats << "Formats to write to: ";
1357  * for (int i = 0; i < GroupTransform::GetNumWriteFormats(); ++i)
1358  * {
1359  * if (i != 0) formats << ", ";
1360  * formats << GroupTransform::GetFormatNameByIndex(i);
1361  * formats << " (." << GroupTransform::GetFormatExtensionByIndex(i) << ")";
1362  * }
1363  * \endcode
1364  */
1365  virtual void write(const ConstConfigRcPtr & config,
1366  const char * formatName,
1367  std::ostream & os) const = 0;
1368 
1369  /// Get the number of writers.
1370  static int GetNumWriteFormats() noexcept;
1371 
1372  /// Get the writer at index, return empty string if an invalid index is specified.
1373  static const char * GetFormatNameByIndex(int index) noexcept;
1374  static const char * GetFormatExtensionByIndex(int index) noexcept;
1375 
1376  GroupTransform(const GroupTransform &) = delete;
1377  GroupTransform & operator=(const GroupTransform &) = delete;
1378  /// Do not use (needed only for pybind11).
1379  virtual ~GroupTransform() = default;
1380 
1381 protected:
1382  GroupTransform() = default;
1383 };
1384 
1385 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const GroupTransform &);
1386 
1387 
1388 
1389 /**
1390  * Applies a logarithm with an affine transform before and after.
1391  * Represents the Cineon lin-to-log type transforms::
1392  *
1393  * logSideSlope * log( linSideSlope * color + linSideOffset, base) + logSideOffset
1394  *
1395  * * Default values are: 1. * log( 1. * color + 0., 2.) + 0.
1396  * * The alpha channel is not affected.
1397  */
1398 class OCIOEXPORT LogAffineTransform : public Transform
1399 {
1400 public:
1401  static LogAffineTransformRcPtr Create();
1402 
1403  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_LOG_AFFINE; }
1404 
1405  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1406  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1407 
1408  /// Checks if this exactly equals other.
1409  virtual bool equals(const LogAffineTransform & other) const noexcept = 0;
1410 
1411  virtual double getBase() const noexcept = 0;
1412  virtual void setBase(double base) noexcept = 0;
1413 
1414  // !rst:: **Get/Set values for the R, G, B components**
1415 
1416  virtual void getLogSideSlopeValue(double(&values)[3]) const noexcept = 0;
1417  virtual void setLogSideSlopeValue(const double(&values)[3]) noexcept = 0;
1418  virtual void getLogSideOffsetValue(double(&values)[3]) const noexcept = 0;
1419  virtual void setLogSideOffsetValue(const double(&values)[3]) noexcept = 0;
1420  virtual void getLinSideSlopeValue(double(&values)[3]) const noexcept = 0;
1421  virtual void setLinSideSlopeValue(const double(&values)[3]) noexcept = 0;
1422  virtual void getLinSideOffsetValue(double(&values)[3]) const noexcept = 0;
1423  virtual void setLinSideOffsetValue(const double(&values)[3]) noexcept = 0;
1424 
1425  LogAffineTransform(const LogAffineTransform &) = delete;
1426  LogAffineTransform & operator= (const LogAffineTransform &) = delete;
1427  /// Do not use (needed only for pybind11).
1428  virtual ~LogAffineTransform() = default;
1429 
1430 protected:
1431  LogAffineTransform() = default;
1432 };
1433 
1434 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const LogAffineTransform &);
1435 
1436 
1437 /**
1438  * Same as LogAffineTransform but with the addition of a linear segment near black. This formula
1439  * is used for many camera logs (e.g., LogC) as well as ACEScct.
1440  *
1441  * * The linSideBreak specifies the point on the linear axis where the log and linear
1442  * segments meet. It must be set (there is no default).
1443  * * The linearSlope specifies the slope of the linear segment of the forward (linToLog)
1444  * transform. By default it is set equal to the slope of the log curve at the break point.
1445  */
1447 {
1448 public:
1449  /// LinSideBreak must be set for the transform to be valid (there is no default).
1450  static LogCameraTransformRcPtr Create(const double(&linSideBreakValues)[3]);
1451 
1452  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_LOG_CAMERA; }
1453 
1454  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1455  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1456 
1457  /// Checks if this exactly equals other.
1458  virtual bool equals(const LogCameraTransform & other) const noexcept = 0;
1459 
1460  virtual double getBase() const noexcept = 0;
1461  virtual void setBase(double base) noexcept = 0;
1462 
1463  /// Get/Set values for the R, G, B components.
1464  virtual void getLogSideSlopeValue(double(&values)[3]) const noexcept = 0;
1465  virtual void setLogSideSlopeValue(const double(&values)[3]) noexcept = 0;
1466  virtual void getLogSideOffsetValue(double(&values)[3]) const noexcept = 0;
1467  virtual void setLogSideOffsetValue(const double(&values)[3]) noexcept = 0;
1468  virtual void getLinSideSlopeValue(double(&values)[3]) const noexcept = 0;
1469  virtual void setLinSideSlopeValue(const double(&values)[3]) noexcept = 0;
1470  virtual void getLinSideOffsetValue(double(&values)[3]) const noexcept = 0;
1471  virtual void setLinSideOffsetValue(const double(&values)[3]) noexcept = 0;
1472  virtual void getLinSideBreakValue(double(&values)[3]) const noexcept = 0;
1473  virtual void setLinSideBreakValue(const double(&values)[3]) noexcept = 0;
1474 
1475  /// Return true if LinearSlope values were set, false if they were not.
1476  virtual bool getLinearSlopeValue(double(&values)[3]) const = 0;
1477  /**
1478  * \brief Set LinearSlope value.
1479  *
1480  * \note
1481  * You must call setLinSideBreakValue before calling this.
1482  */
1483  virtual void setLinearSlopeValue(const double(&values)[3]) = 0;
1484  /// Remove LinearSlope values so that default values are used.
1485  virtual void unsetLinearSlopeValue() = 0;
1486 
1487  LogCameraTransform(const LogCameraTransform &) = delete;
1488  LogCameraTransform & operator= (const LogCameraTransform &) = delete;
1489  /// Do not use (needed only for pybind11).
1490  virtual ~LogCameraTransform() = default;
1491 
1492 protected:
1493  LogCameraTransform() = default;
1494 };
1495 
1496 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const LogCameraTransform &);
1497 
1498 
1499 /**
1500  * Represents log transform: log(color, base)
1501  *
1502  * * The input will be clamped for negative numbers.
1503  * * Default base is 2.0.
1504  * * The alpha channel is not affected.
1505  */
1506 class OCIOEXPORT LogTransform : public Transform
1507 {
1508 public:
1509  static LogTransformRcPtr Create();
1510 
1511  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_LOG; }
1512 
1513  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1514  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1515 
1516  /// Checks if this exactly equals other.
1517  virtual bool equals(const LogTransform & other) const noexcept = 0;
1518 
1519  virtual double getBase() const noexcept = 0;
1520  virtual void setBase(double val) noexcept = 0;
1521 
1522  LogTransform(const LogTransform &) = delete;
1523  LogTransform & operator= (const LogTransform &) = delete;
1524  /// Do not use (needed only for pybind11).
1525  virtual ~LogTransform() = default;
1526 
1527 protected:
1528  LogTransform() = default;
1529 };
1530 
1531 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const LogTransform &);
1532 
1533 
1534 class OCIOEXPORT LookTransform : public Transform
1535 {
1536 public:
1537  static LookTransformRcPtr Create();
1538 
1539  TransformRcPtr createEditableCopy() const override;
1540 
1541  TransformDirection getDirection() const noexcept override;
1542  void setDirection(TransformDirection dir) noexcept override;
1543 
1544  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_LOOK; }
1545 
1546  /// Will throw if data is not valid.
1547  void validate() const override;
1548 
1549  const char * getSrc() const;
1550  void setSrc(const char * src);
1551 
1552  const char * getDst() const;
1553  void setDst(const char * dst);
1554 
1555  const char * getLooks() const;
1556  /**
1557  * Specify looks to apply.
1558  * Looks is a potentially comma (or colon) delimited list of look names,
1559  * Where +/- prefixes are optionally allowed to denote forward/inverse
1560  * look specification. (And forward is assumed in the absence of either)
1561  */
1562  void setLooks(const char * looks);
1563 
1564  bool getSkipColorSpaceConversion() const;
1565  void setSkipColorSpaceConversion(bool skip);
1566 
1567  /**
1568  * Return the name of the color space after applying looks in the forward
1569  * direction but without converting to the destination color space. This is equivalent
1570  * to the process space of the last look in the look sequence (and takes into account that
1571  * a look fall-back may be used).
1572  */
1573  static const char * GetLooksResultColorSpace(const ConstConfigRcPtr & config,
1574  const ConstContextRcPtr & context,
1575  const char * looks);
1576 
1577  LookTransform & operator=(const LookTransform &) = delete;
1578  /// Do not use (needed only for pybind11).
1579  virtual ~LookTransform();
1580 
1581 private:
1582  LookTransform();
1583  LookTransform(const LookTransform &);
1584 
1585  static void deleter(LookTransform * t);
1586 
1587  class Impl;
1588  Impl * m_impl;
1589  Impl * getImpl() { return m_impl; }
1590  const Impl * getImpl() const { return m_impl; }
1591 };
1592 
1593 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const LookTransform &);
1594 
1595 
1596 /// Represents a 1D-LUT transform.
1597 class OCIOEXPORT Lut1DTransform : public Transform
1598 {
1599 public:
1600  /// Create an identity 1D-LUT of length two.
1601  static Lut1DTransformRcPtr Create();
1602 
1603  /**
1604  * Create an identity 1D-LUT with specific length and
1605  * half-domain setting. Will throw for lengths longer than 1024x1024.
1606  */
1607  static Lut1DTransformRcPtr Create(unsigned long length,
1608  bool isHalfDomain);
1609 
1610  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_LUT1D; }
1611 
1612  virtual BitDepth getFileOutputBitDepth() const noexcept = 0;
1613  /**
1614  * Get the bit-depth associated with the LUT values read
1615  * from a file or set the bit-depth of values to be written to a file
1616  * (for file formats such as CLF that support multiple bit-depths).
1617  * However, note that the values stored in the object are always
1618  * normalized.
1619  */
1620  virtual void setFileOutputBitDepth(BitDepth bitDepth) noexcept = 0;
1621 
1622  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1623  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1624 
1625  /// Checks if this exactly equals other.
1626  virtual bool equals(const Lut1DTransform & other) const noexcept = 0;
1627 
1628  virtual unsigned long getLength() const = 0;
1629  /**
1630  * Changing the length will reset the LUT to identity.
1631  * Will throw for lengths longer than 1024x1024.
1632  */
1633  virtual void setLength(unsigned long length) = 0;
1634 
1635  virtual void getValue(unsigned long index, float & r, float & g, float & b) const = 0;
1636  /**
1637  * Set the values of a LUT1D. Will throw if the index
1638  * is outside of the range from 0 to (length-1).
1639  *
1640  * The LUT values are always for the "forward" LUT, regardless of how
1641  * the transform direction is set.
1642  *
1643  * These values are normalized relative to what may be stored in any
1644  * given LUT files. For example in a CLF file using a "10i" output
1645  * depth, a value of 1023 in the file is normalized to 1.0. The
1646  * values here are unclamped and may extend outside [0,1].
1647  *
1648  * LUTs in various file formats may only provide values for one
1649  * channel where R, G, B are the same. Even in that case, you should
1650  * provide three equal values to the setter.
1651  */
1652  virtual void setValue(unsigned long index, float r, float g, float b) = 0;
1653 
1654  virtual bool getInputHalfDomain() const noexcept = 0;
1655  /**
1656  * In a half-domain LUT, the contents of the LUT specify
1657  * the desired value of the function for each half-float value.
1658  * Therefore, the length of the LUT must be 65536 entries or else
1659  * validate() will throw.
1660  */
1661  virtual void setInputHalfDomain(bool isHalfDomain) noexcept = 0;
1662 
1663  virtual bool getOutputRawHalfs() const noexcept = 0;
1664  /**
1665  * Set OutputRawHalfs to true if you want to output the
1666  * LUT contents as 16-bit floating point values expressed as unsigned
1667  * 16-bit integers representing the equivalent bit pattern.
1668  * For example, the value 1.0 would be written as the integer 15360
1669  * because it has the same bit-pattern. Note that this implies the
1670  * values will be quantized to a 16-bit float. Note that this setting
1671  * only controls the output formatting (where supported) and not the
1672  * values for getValue/setValue. The only file formats that currently
1673  * support this are CLF and CTF.
1674  */
1675  virtual void setOutputRawHalfs(bool isRawHalfs) noexcept = 0;
1676 
1677  virtual Lut1DHueAdjust getHueAdjust() const noexcept = 0;
1678  /**
1679  * The 1D-LUT transform optionally supports a hue adjustment
1680  * feature that was used in some versions of ACES. This adjusts the hue
1681  * of the result to approximately match the input.
1682  */
1683  virtual void setHueAdjust(Lut1DHueAdjust algo) = 0;
1684 
1685  virtual Interpolation getInterpolation() const = 0;
1686  virtual void setInterpolation(Interpolation algo) = 0;
1687 
1688  Lut1DTransform(const Lut1DTransform &) = delete;
1689  Lut1DTransform & operator= (const Lut1DTransform &) = delete;
1690  /// Do not use (needed only for pybind11).
1691  virtual ~Lut1DTransform() = default;
1692 
1693 protected:
1694  Lut1DTransform() = default;
1695 };
1696 
1697 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Lut1DTransform&);
1698 
1699 
1700 /// Represents a 3D-LUT transform.
1701 class OCIOEXPORT Lut3DTransform : public Transform
1702 {
1703 public:
1704  /// Create an identity 3D-LUT of size 2x2x2.
1705  static Lut3DTransformRcPtr Create();
1706 
1707  /**
1708  * Create an identity 3D-LUT with specific grid size.
1709  * Will throw for grid size larger than 129.
1710  */
1711  static Lut3DTransformRcPtr Create(unsigned long gridSize);
1712 
1713  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_LUT3D; }
1714 
1715  virtual BitDepth getFileOutputBitDepth() const noexcept = 0;
1716  /**
1717  * Get the bit-depth associated with the LUT values read
1718  * from a file or set the bit-depth of values to be written to a file
1719  * (for file formats such as CLF that support multiple bit-depths).
1720  * However, note that the values stored in the object are always
1721  * normalized.
1722  */
1723  virtual void setFileOutputBitDepth(BitDepth bitDepth) noexcept = 0;
1724 
1725  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1726  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1727 
1728  /// Checks if this exactly equals other.
1729  virtual bool equals(const Lut3DTransform & other) const noexcept = 0;
1730 
1731  virtual unsigned long getGridSize() const = 0;
1732  /**
1733  * Changing the grid size will reset the LUT to identity.
1734  * Will throw for grid sizes larger than 129.
1735  */
1736  virtual void setGridSize(unsigned long gridSize) = 0;
1737 
1738  virtual void getValue(unsigned long indexR,
1739  unsigned long indexG,
1740  unsigned long indexB,
1741  float & r, float & g, float & b) const = 0;
1742  /**
1743  * Set the values of a 3D-LUT. Will throw if an index is
1744  * outside of the range from 0 to (gridSize-1).
1745  *
1746  * The LUT values are always for the "forward" LUT, regardless of how the
1747  * transform direction is set.
1748  *
1749  * These values are normalized relative to what may be stored in any
1750  * given LUT files. For example in a CLF file using a "10i" output
1751  * depth, a value of 1023 in the file is normalized to 1.0. The values
1752  * here are unclamped and may extend outside [0,1].
1753  */
1754  virtual void setValue(unsigned long indexR,
1755  unsigned long indexG,
1756  unsigned long indexB,
1757  float r, float g, float b) = 0;
1758 
1759  virtual Interpolation getInterpolation() const = 0;
1760  virtual void setInterpolation(Interpolation algo) = 0;
1761 
1762  Lut3DTransform(const Lut3DTransform &) = delete;
1763  Lut3DTransform & operator= (const Lut3DTransform &) = delete;
1764  /// Do not use (needed only for pybind11).
1765  virtual ~Lut3DTransform() = default;
1766 
1767 protected:
1768  Lut3DTransform() = default;
1769 };
1770 
1771 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Lut3DTransform&);
1772 
1773 /**
1774  * Represents an MX+B Matrix transform.
1775  *
1776  * \note
1777  * For singular matrices, an inverse direction will throw an exception during finalization.
1778  */
1780 {
1781 public:
1782  static MatrixTransformRcPtr Create();
1783 
1784  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_MATRIX; }
1785 
1786  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1787  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1788 
1789  /// Checks if this exactly equals other.
1790  virtual bool equals(const MatrixTransform & other) const noexcept = 0;
1791 
1792  virtual void getMatrix(double * m44) const = 0;
1793  /**
1794  * Get or set the values of a Matrix. Expects 16 values,
1795  * where the first four are the coefficients to generate the R output
1796  * channel from R, G, B, A input channels.
1797  *
1798  * The Matrix values are always for the "forward" Matrix, regardless of
1799  * how the transform direction is set.
1800  *
1801  * These values are normalized relative to what may be stored in
1802  * file formats such as CLF. For example in a CLF file using a "32f"
1803  * input depth and "10i" output depth, a value of 1023 in the file
1804  * is normalized to 1.0. The values here are unclamped and may
1805  * extend outside [0,1].
1806  */
1807  virtual void setMatrix(const double * m44) = 0;
1808 
1809  virtual void getOffset(double * offset4) const = 0;
1810  /**
1811  * Get or set the R, G, B, A offsets to be applied
1812  * after the matrix.
1813  *
1814  * These values are normalized relative to what may be stored in
1815  * file formats such as CLF. For example, in a CLF file using a
1816  * "10i" output depth, a value of 1023 in the file is normalized
1817  * to 1.0. The values here are unclamped and may extend
1818  * outside [0,1].
1819  */
1820  virtual void setOffset(const double * offset4) = 0;
1821 
1822  /**
1823  * Get the bit-depths associated with the matrix values read from a
1824  * file or set the bit-depths of values to be written to a file
1825  * (for file formats such as CLF that support multiple bit-depths).
1826  *
1827  * In a format such as CLF, the matrix values are scaled to take
1828  * pixels at the specified inBitDepth to pixels at the specified
1829  * outBitDepth. This complicates the interpretation of the matrix
1830  * values and so this object always holds normalized values and
1831  * scaling is done on the way from or to file formats such as CLF.
1832  */
1833  virtual BitDepth getFileInputBitDepth() const noexcept = 0;
1834  virtual void setFileInputBitDepth(BitDepth bitDepth) noexcept = 0;
1835  virtual BitDepth getFileOutputBitDepth() const noexcept = 0;
1836  virtual void setFileOutputBitDepth(BitDepth bitDepth) noexcept = 0;
1837 
1838 
1839  /// **Convenience functions**
1840  ///
1841  /// Build the matrix and offset corresponding to higher-level concepts.
1842  ///
1843  /// \note
1844  /// These can throw an exception if for any component
1845  /// ``oldmin == oldmax. (divide by 0)``
1846  static void Fit(double * m44, double* offset4,
1847  const double * oldmin4, const double * oldmax4,
1848  const double * newmin4, const double * newmax4);
1849 
1850  static void Identity(double * m44, double * offset4);
1851 
1852  static void Sat(double * m44, double * offset4,
1853  double sat, const double * lumaCoef3);
1854 
1855  static void Scale(double * m44, double * offset4,
1856  const double * scale4);
1857 
1858  static void View(double * m44, double * offset4,
1859  int * channelHot4,
1860  const double * lumaCoef3);
1861 
1862  MatrixTransform(const MatrixTransform &) = delete;
1863  MatrixTransform & operator= (const MatrixTransform &) = delete;
1864  /// Do not use (needed only for pybind11).
1865  virtual ~MatrixTransform() = default;
1866 
1867 protected:
1868  MatrixTransform() = default;
1869 };
1870 
1871 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const MatrixTransform &) noexcept;
1872 
1873 
1874 /**
1875  * Represents a range transform
1876  *
1877  * The Range is used to apply an affine transform (scale & offset) and
1878  * clamps values to min/max bounds on all color components except the alpha.
1879  * The scale and offset values are computed from the input and output bounds.
1880  *
1881  * Refer to section 7.2.4 in specification S-2014-006 "A Common File Format
1882  * for Look-Up Tables" from the Academy of Motion Picture Arts and Sciences
1883  * and the American Society of Cinematographers.
1884  *
1885  * \note
1886  * The "noClamp" style described in the specification S-2014-006 becomes a
1887  * MatrixOp at the processor level.
1888  *
1889  * \note
1890  * Changing the transform direction does not modify the in/out values --
1891  * they are always specified with respect to the "forward" direction.
1892  */
1893 class OCIOEXPORT RangeTransform : public Transform
1894 {
1895 public:
1896  /// Creates an instance of RangeTransform.
1897  static RangeTransformRcPtr Create();
1898 
1899  TransformType getTransformType() const noexcept override { return TRANSFORM_TYPE_RANGE; }
1900 
1901  virtual RangeStyle getStyle() const noexcept = 0;
1902  /// Set the Range style to clamp or not input values.
1903  virtual void setStyle(RangeStyle style) noexcept = 0;
1904 
1905  virtual const FormatMetadata & getFormatMetadata() const noexcept = 0;
1906  virtual FormatMetadata & getFormatMetadata() noexcept = 0;
1907 
1908  /// Checks if this equals other.
1909  virtual bool equals(const RangeTransform & other) const noexcept = 0;
1910 
1911  /**
1912  * **File bit-depth**
1913  *
1914  * In a format such as CLF, the range values are scaled to take
1915  * pixels at the specified inBitDepth to pixels at the specified
1916  * outBitDepth. This complicates the interpretation of the range
1917  * values and so this object always holds normalized values and
1918  * scaling is done on the way from or to file formats such as CLF.
1919  */
1920 
1921  /// Get the bit-depths associated with the range values read from a file
1922  /// or set the bit-depths of values to be written to a file (for file
1923  /// formats such as CLF that support multiple bit-depths).
1924  virtual BitDepth getFileInputBitDepth() const noexcept = 0;
1925  virtual void setFileInputBitDepth(BitDepth bitDepth) noexcept = 0;
1926  virtual BitDepth getFileOutputBitDepth() const noexcept = 0;
1927  virtual void setFileOutputBitDepth(BitDepth bitDepth) noexcept = 0;
1928 
1929  /**
1930  * **Range values**
1931  *
1932  * These values are normalized relative to what may be stored in file
1933  * formats such as CLF. For example in a CLF file using a "10i" input
1934  * depth, a MaxInValue of 1023 in the file is normalized to 1.0.
1935  * Likewise, for an output depth of "12i", a MaxOutValue of 4095 in the
1936  * file is normalized to 1.0. The values here are unclamped and may
1937  * extend outside [0,1].
1938  */
1939 
1940  /// Get the minimum value for the input.
1941  virtual double getMinInValue() const noexcept = 0;
1942  /// Set the minimum value for the input.
1943  virtual void setMinInValue(double val) noexcept = 0;
1944  /// Is the minimum value for the input set?
1945  virtual bool hasMinInValue() const noexcept = 0;
1946  /// Unset the minimum value for the input
1947  virtual void unsetMinInValue() noexcept = 0;
1948 
1949  /// Set the maximum value for the input.
1950  virtual void setMaxInValue(double val) noexcept = 0;
1951  /// Get the maximum value for the input.
1952  virtual double getMaxInValue() const noexcept = 0;
1953  /// Is the maximum value for the input set?
1954  virtual bool hasMaxInValue() const noexcept = 0;
1955  /// Unset the maximum value for the input.
1956  virtual void unsetMaxInValue() noexcept = 0;
1957 
1958  /// Set the minimum value for the output.
1959  virtual void setMinOutValue(double val) noexcept = 0;
1960  /// Get the minimum value for the output.
1961  virtual double getMinOutValue() const noexcept = 0;
1962  /// Is the minimum value for the output set?
1963  virtual bool hasMinOutValue() const noexcept = 0;
1964  /// Unset the minimum value for the output.
1965  virtual void unsetMinOutValue() noexcept = 0;
1966 
1967  /// Set the maximum value for the output.
1968  virtual void setMaxOutValue(double val) noexcept = 0;
1969  /// Get the maximum value for the output.
1970  virtual double getMaxOutValue() const noexcept = 0;
1971  /// Is the maximum value for the output set?
1972  virtual bool hasMaxOutValue() const noexcept = 0;
1973  /// Unset the maximum value for the output.
1974  virtual void unsetMaxOutValue() noexcept = 0;
1975 
1976  RangeTransform(const RangeTransform &) = delete;
1977  RangeTransform & operator= (const RangeTransform &) = delete;
1978  /// Do not use (needed only for pybind11).
1979  virtual ~RangeTransform() = default;
1980 
1981 protected:
1982  RangeTransform() = default;
1983 };
1984 
1985 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const RangeTransform &) noexcept;
1986 
1987 } // namespace OCIO_NAMESPACE
1988 
1989 #endif
OCIO_SHARED_PTR< DisplayViewTransform > DisplayViewTransformRcPtr
2D control point used by GradingBSplineCurve.
Represents exponent transform: pow( clamp(color), value ).
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1222
TransformType getTransformType() const noexceptoverride
TransformType getTransformType() const noexceptoverride
TransformType getTransformType() const noexceptoverride
OCIO_SHARED_PTR< LookTransform > LookTransformRcPtr
*get result *(waiting if necessary)*A common idiom is to fire a bunch of sub tasks at the and then *wait for them to all complete We provide a helper class
Definition: thread.h:623
RangeStyle
A RangeTransform may be set to clamp the values, or not.
void skip(T &in, int n)
Definition: ImfXdr.h:711
Algorithms for Scene Linear color spaces.
Represents a 1D-LUT transform.
OCIO_SHARED_PTR< ExponentTransform > ExponentTransformRcPtr
GradingRGBMSW(const double(&rgbmsw)[6])
GLuint start
Definition: glcorearb.h:475
OCIO_SHARED_PTR< DynamicPropertyGradingTone > DynamicPropertyGradingToneRcPtr
const GLfloat * c
Definition: glew.h:16631
GLboolean GLboolean g
Definition: glcorearb.h:1222
GLfloat GLfloat blue
Definition: glcorearb.h:112
TransformType getTransformType() const noexceptoverride
Interface used to access dynamic property double value.
OCIO_SHARED_PTR< const Transform > ConstTransformRcPtr
OCIO_SHARED_PTR< AllocationTransform > AllocationTransformRcPtr
bool isIdentity(const MatType &m)
Determine if a matrix is an identity matrix.
Definition: Mat.h:882
GradingRGBM(const double(&rgbm)[4])
OCIO_SHARED_PTR< Lut1DTransform > Lut1DTransformRcPtr
#define OCIO_NAMESPACE
Definition: OpenColorABI.h:8
OCIO_SHARED_PTR< LogCameraTransform > LogCameraTransformRcPtr
DynamicPropertyType
Types for dynamic properties.
GradingRGBM(double red, double green, double blue, double master)
GLenum GLenum GLsizei const GLuint GLboolean enabled
Definition: glcorearb.h:2539
GLuint const GLchar * name
Definition: glcorearb.h:786
Interface used to access dynamic property GradingTone value.
GradingRGBMSW(double start, double width)
class OCIOEXPORT DynamicProperty
GLenum src
Definition: glcorearb.h:1793
TransformType getTransformType() const noexceptoverride
GLdouble GLdouble t
Definition: glew.h:1403
OCIO_SHARED_PTR< FixedFunctionTransform > FixedFunctionTransformRcPtr
OCIOEXPORT DynamicPropertyGradingPrimaryRcPtr AsGradingPrimary(DynamicPropertyRcPtr &prop)
OCIO_SHARED_PTR< DynamicPropertyGradingRGBCurve > DynamicPropertyGradingRGBCurveRcPtr
OCIO_SHARED_PTR< ExponentWithLinearTransform > ExponentWithLinearTransformRcPtr
GLenum GLsizei GLsizei GLint * values
Definition: glcorearb.h:1602
GLint GLenum GLint x
Definition: glcorearb.h:409
TransformType getTransformType() const noexceptoverride
GLsizeiptr size
Definition: glcorearb.h:664
GLuint GLenum GLenum transform
Definition: glew.h:15055
TransformType getTransformType() const noexceptoverride
class OCIOEXPORT LookTransform
TransformType getTransformType() const noexceptoverride
OCIO_SHARED_PTR< ColorSpaceTransform > ColorSpaceTransformRcPtr
OCIO_SHARED_PTR< const Context > ConstContextRcPtr
TransformType getTransformType() const noexceptoverride
Interface used to access dynamic property ConstGradingRGBCurveRcPtr value.
Algorithms for Logarithmic color spaces.
OCIO_SHARED_PTR< DynamicPropertyDouble > DynamicPropertyDoubleRcPtr
TransformType getTransformType() const noexceptoverride
OCIO_SHARED_PTR< Lut3DTransform > Lut3DTransformRcPtr
OCIOEXPORT DynamicPropertyGradingRGBCurveRcPtr AsGradingRGBCurve(DynamicPropertyRcPtr &prop)
OCIO_SHARED_PTR< ExposureContrastTransform > ExposureContrastTransformRcPtr
TransformType getTransformType() const noexceptoverride
OCIO_SHARED_PTR< LogTransform > LogTransformRcPtr
GLuint interp
Definition: glew.h:8307
class OCIOEXPORT GroupTransform
TransformType getTransformType() const noexceptoverride
class OCIOEXPORT GradingBSplineCurve
TransformType getTransformType() const noexceptoverride
GLuint num
Definition: glew.h:2695
TransformType getTransformType() const noexceptoverride
#define OCIOEXPORT
Definition: OpenColorABI.h:67
class OCIOEXPORT Transform
OCIO_SHARED_PTR< GradingPrimaryTransform > GradingPrimaryTransformRcPtr
OCIO_SHARED_PTR< GradingBSplineCurve > GradingBSplineCurveRcPtr
TransformType getTransformType() const noexceptoverride
class OCIOEXPORT GradingRGBCurve
OCIO_SHARED_PTR< GradingRGBCurve > GradingRGBCurveRcPtr
An implementation of the ASC Color Decision List (CDL), based on the ASC v1.2 specification.
GLint GLsizei width
Definition: glcorearb.h:103
Base class for all the transform classes.
TransformType getTransformType() const noexceptoverride
OCIO_SHARED_PTR< MatrixTransform > MatrixTransformRcPtr
OCIO_SHARED_PTR< Transform > TransformRcPtr
GradingStyle
Styles for grading transforms.
TransformType getTransformType() const noexceptoverride
class OCIOEXPORT DynamicPropertyGradingPrimary
GLuint GLsizei GLsizei * length
Definition: glcorearb.h:795
GLuint GLfloat * val
Definition: glcorearb.h:1608
OCIO_SHARED_PTR< const Config > ConstConfigRcPtr
OCIO_SHARED_PTR< RangeTransform > RangeTransformRcPtr
OCIO_SHARED_PTR< GradingToneTransform > GradingToneTransformRcPtr
OCIO_SHARED_PTR< DynamicPropertyGradingPrimary > DynamicPropertyGradingPrimaryRcPtr
TransformType getTransformType() const noexceptoverride
GLboolean red
Definition: glew.h:2176
TransformType getTransformType() const noexceptoverride
Interface used to access dynamic property GradingPrimary value.
GLuint index
Definition: glcorearb.h:786
GLfloat green
Definition: glcorearb.h:112
OCIO_SHARED_PTR< BuiltinTransform > BuiltinTransformRcPtr
OCIO_SHARED_PTR< FileTransform > FileTransformRcPtr
GA_API const UT_StringHolder pivot
Lut1DHueAdjust
Used by :cpp:classLut1DTransform to control optional hue restoration algorithm.
OCIO_SHARED_PTR< const GradingBSplineCurve > ConstGradingBSplineCurveRcPtr
class OCIOEXPORT AllocationTransform
OCIO_SHARED_PTR< LogAffineTransform > LogAffineTransformRcPtr
GLenum const GLfloat * params
Definition: glcorearb.h:105
OCIOEXPORT std::ostream & operator<<(std::ostream &, const ColorSpaceMenuParameters &)
Definition: core.h:982
FixedFunctionStyle
Enumeration of the :cpp:class:FixedFunctionTransform transform algorithms.
Definition: core.h:1131
OCIO_SHARED_PTR< GroupTransform > GroupTransformRcPtr
Represents a 3D-LUT transform.
OCIOEXPORT DynamicPropertyDoubleRcPtr AsDouble(DynamicPropertyRcPtr &prop)
class OCIOEXPORT FileTransform
#define const
Definition: zconf.h:214
GradingRGBMSW(double red, double green, double blue, double master, double start, double width)
OCIO_SHARED_PTR< CDLTransform > CDLTransformRcPtr
GLenum GLenum dst
Definition: glcorearb.h:1793
GLboolean r
Definition: glcorearb.h:1222
class OCIOEXPORT DynamicPropertyGradingTone
void write(T &out, bool v)
Definition: ImfXdr.h:287
OCIO_SHARED_PTR< GradingRGBCurveTransform > GradingRGBCurveTransformRcPtr
A BSpline curve defined with GradingControlPoint.
TransformType getTransformType() const noexceptoverride
class OCIOEXPORT DisplayViewTransform
OCIO_SHARED_PTR< const GradingRGBCurve > ConstGradingRGBCurveRcPtr
GLint y
Definition: glcorearb.h:103
RGBCurveType
Types for GradingRGBCurve.
class OCIOEXPORT DynamicPropertyDouble
TransformType getTransformType() const noexceptoverride
OCIOEXPORT DynamicPropertyGradingToneRcPtr AsGradingTone(DynamicPropertyRcPtr &prop)
ExposureContrastStyle
Enumeration of the :cpp:class:ExposureContrastTransform transform algorithms.
OCIO_SHARED_PTR< DynamicProperty > DynamicPropertyRcPtr
class OCIOEXPORT DynamicPropertyGradingRGBCurve