HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
OpenColorIO.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_OPENCOLORIO_H
6 #define INCLUDED_OCIO_OPENCOLORIO_H
7 
8 #include <cstddef>
9 #include <iosfwd>
10 #include <limits>
11 #include <stdexcept>
12 #include <string>
13 
14 #include "OpenColorABI.h"
15 #include "OpenColorTypes.h"
16 #include "OpenColorTransforms.h"
17 #include "OpenColorAppHelpers.h"
18 
19 
20 /*
21 
22 C++ API
23 =======
24 
25 **Usage Example:** *Compositing plugin that converts from "log" to "lin"*
26 
27 .. code-block:: cpp
28 
29  #include <OpenColorIO/OpenColorIO.h>
30  namespace OCIO = OCIO_NAMESPACE;
31 
32  try
33  {
34  // Get the global OpenColorIO config
35  // This will auto-initialize (using $OCIO) on first use
36  OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig();
37 
38  // Get the processor corresponding to this transform.
39  OCIO::ConstProcessorRcPtr processor = config->getProcessor(OCIO::ROLE_COMPOSITING_LOG,
40  OCIO::ROLE_SCENE_LINEAR);
41 
42  // Get the corresponding CPU processor for 32-bit float image processing.
43  OCIO::ConstCPUProcessorRcPtr cpuProcessor = processor->getDefaultCPUProcessor();
44 
45  // Wrap the image in a light-weight ImageDescription
46  OCIO::PackedImageDesc img(imageData, w, h, 4);
47 
48  // Apply the color transformation (in place)
49  cpuProcessor->apply(img);
50  }
51  catch(OCIO::Exception & exception)
52  {
53  std::cerr << "OpenColorIO Error: " << exception.what() << std::endl;
54  }
55 
56 */
57 
58 namespace OCIO_NAMESPACE
59 {
60 ///////////////////////////////////////////////////////////////////////////
61 // Exceptions
62 
63 // Silence warning C4275 under Visual Studio:
64 // Exceptions derive from std::runtime_error but STL classes are not exportable.
65 #ifdef _MSC_VER
66 #pragma warning( push )
67 #pragma warning( disable : 4275 )
68 #endif
69 
70 /**
71  * \brief An exception class to throw for errors detected at runtime.
72  *
73  * \warning
74  * All functions in the Config class can potentially throw this exception.
75  */
76 class OCIOEXPORT Exception : public std::runtime_error
77 {
78 public:
79  Exception() = delete;
80  /// Constructor that takes a string as the exception message.
81  explicit Exception(const char *);
82  /// Constructor that takes an existing exception.
83  Exception(const Exception &);
84  Exception & operator= (const Exception &) = delete;
85 
86  ~Exception();
87 };
88 
89 /**
90  * \brief An exception class for errors detected at runtime.
91  *
92  * Thrown when OCIO cannot find a file that is expected to exist. This is provided as a custom
93  * type to distinguish cases where one wants to continue looking for missing files, but wants
94  * to properly fail for other error conditions.
95  */
97 {
98 public:
99  ExceptionMissingFile() = delete;
100  /// Constructor that takes a string as the exception message.
101  explicit ExceptionMissingFile(const char *);
102  /// Constructor that takes an existing exception.
104  ExceptionMissingFile & operator= (const ExceptionMissingFile &) = delete;
105 
107 };
108 
109 // Restore default warning behaviour for Visual Studio.
110 #ifdef _MSC_VER
111 #pragma warning( pop )
112 #endif
113 
114 ///////////////////////////////////////////////////////////////////////////
115 // Global
116 // ******
117 
118 /**
119  * During normal usage, OpenColorIO tends to cache certain global information (such
120  * as the contents of LUTs on disk, intermediate results, etc.). Calling this function will flush
121  * all such information. The global information are related to LUT file identifications, loaded LUT
122  * file content and CDL transforms from loaded CDL files.
123  *
124  * Under normal usage, this is not necessary, but it can be helpful in particular instances,
125  * such as designing OCIO profiles, and wanting to re-read luts without restarting.
126  *
127  * \note The method does not apply to instance specific caches such as the processor cache in a
128  * config instance or the GPU and CPU processor caches in a processor instance. Here deleting the
129  * instance flushes the cache.
130  */
131 extern OCIOEXPORT void ClearAllCaches();
132 
133 /**
134  * \brief Get the version number for the library, as a dot-delimited string
135  * (e.g., "1.0.0").
136  *
137  * This is also available at compile time as OCIO_VERSION_FULL_STR.
138  */
139 extern OCIOEXPORT const char * GetVersion();
140 
141 /**
142  * \brief Get the version number for the library, as a
143  * single 4-byte hex number (e.g., 0x01050200 for "1.5.2"), to be used
144  * for numeric comparisons.
145  *
146  * This is also at compile time as OCIO_VERSION_HEX.
147  */
148 extern OCIOEXPORT int GetVersionHex();
149 
150 /**
151  * \brief Get the global logging level.
152  *
153  * You can override this at runtime using the \ref OCIO_LOGGING_LEVEL
154  * environment variable. The client application that sets this should use
155  * \ref SetLoggingLevel, and not the environment variable. The default value is INFO.
156  */
158 
159 /// Set the global logging level.
161 
162 /**
163  * \brief Set the logging function to use; otherwise, use the default
164  * (i.e. std::cerr).
165  *
166  * \note
167  * The logging mechanism is thread-safe.
168  */
169 extern OCIOEXPORT void SetLoggingFunction(LoggingFunction logFunction);
171 /// Log a message using the library logging function.
172 extern OCIOEXPORT void LogMessage(LoggingLevel level, const char * message);
173 
174 /**
175  * \brief Set the Compute Hash Function to use; otherwise, use the default.
176  *
177  * \param ComputeHashFunction
178  */
179 extern OCIOEXPORT void SetComputeHashFunction(ComputeHashFunction hashFunction);
181 
182 //
183 // Note that the following environment variable access methods are not thread safe.
184 //
185 
186 /**
187  * Another call modifies the string obtained from a previous call as the method always uses the
188  * same memory buffer.
189  */
190 extern OCIOEXPORT const char * GetEnvVariable(const char * name);
191 /// \warning This method is not thread safe.
192 extern OCIOEXPORT void SetEnvVariable(const char * name, const char * value);
193 /// \warning This method is not thread safe.
194 extern OCIOEXPORT void UnsetEnvVariable(const char * name);
195 //!cpp:function::
196 extern OCIOEXPORT bool IsEnvVariablePresent(const char * name);
197 
198 /// Get the current configuration.
200 
201 /// Set the current configuration. This will then store a copy of the specified config.
202 extern OCIOEXPORT void SetCurrentConfig(const ConstConfigRcPtr & config);
203 
204 /**
205  * \brief
206  * A config defines all the color spaces to be available at runtime.
207  *
208  * The color configuration (Config) is the main object for interacting with this library. It
209  * encapsulates all of the information necessary to use customized ColorSpaceTransform and
210  * DisplayViewTransform operations.
211  *
212  * See the \ref user-guide for more information on selecting, creating, and working with custom
213  * color configurations.
214  *
215  * For applications interested in using only one color config at a time (this is the vast majority
216  * of apps), their API would traditionally get the global configuration and use that, as opposed
217  * to creating a new one. This simplifies the use case for plugins and bindings, as it alleviates
218  * the need to pass around configuration handles.
219  *
220  * An example of an application where this would not be sufficient would be a multi-threaded image
221  * proxy server (daemon), which wished to handle multiple show configurations in a single process
222  * concurrently. This app would need to keep multiple configurations alive, and to manage them
223  * appropriately.
224  *
225  * Roughly speaking, a novice user should select a default configuration that most closely
226  * approximates the use case (animation, visual effects, etc.), and set the :envvar:`OCIO`
227  * environment variable to point at the root of that configuration.
228  *
229  * \note
230  * Initialization using environment variables is typically preferable in
231  * a multi-app ecosystem, as it allows all applications to be
232  * consistently configured.
233  *
234  * See \ref developers-usageexamples
235  */
237 {
238 public:
239 
240  //
241  // Initialization
242  //
243 
244  /**
245  * \brief Create an empty config of the current version.
246  *
247  * Note that an empty config will not pass validation since required elements will be missing.
248  */
249  static ConfigRcPtr Create();
250  /**
251  * \brief Create a fall-back config.
252  *
253  * This may be useful to allow client apps to launch in cases when the
254  * supplied config path is not loadable.
255  */
256  static ConstConfigRcPtr CreateRaw();
257  /**
258  * \brief Create a configuration using the OCIO environment variable.
259  *
260  * If the variable is missing or empty, returns the same result as
261  * \ref Config::CreateRaw .
262  */
263  static ConstConfigRcPtr CreateFromEnv();
264  /// Create a configuration using a specific config file.
265  static ConstConfigRcPtr CreateFromFile(const char * filename);
266  /// Create a configuration using a stream.
267  static ConstConfigRcPtr CreateFromStream(std::istream & istream);
268 
269  ConfigRcPtr createEditableCopy() const;
270 
271  /// Get the configuration major version.
272  unsigned int getMajorVersion() const;
273 
274  /**
275  * Set the configuration major version.
276  *
277  * Throws if it is not supported. Resets minor to the most recent minor for the given major.
278  */
279  void setMajorVersion(unsigned int major);
280 
281  /// Get the configuration minor version.
282  unsigned int getMinorVersion() const;
283 
284  /// Set the configuration minor version. Throws if it is not supported for the current major.
285  void setMinorVersion(unsigned int minor);
286 
287  /// Set the configuration major and minor versions. Throws if version is not supported.
288  void setVersion(unsigned int major, unsigned int minor);
289 
290  /// Allows an older config to be serialized as the current version.
291  void upgradeToLatestVersion() noexcept;
292 
293  /**
294  * \brief Performs a thorough validation for the most common user errors.
295  *
296  * This will throw an exception if the config is malformed. The most
297  * common error occurs when references are made to colorspaces that do not
298  * exist.
299  */
300  void validate() const;
301 
302  /**
303  * \brief Get/set a name string for the config.
304  *
305  * The name string may be used to communicate config update details or similar information
306  * to workflows external to OCIO in cases where the config path/filename itself does not
307  * provide adequate information.
308  */
309  const char * getName() const noexcept;
310  void setName(const char * name) noexcept;
311 
312  /**
313  * \brief Get the family separator
314  *
315  * A single character used to separate the family string into tokens for use in hierarchical
316  * menus. Defaults to '/'.
317  */
318  char getFamilySeparator() const;
319  /// Get the default family separator i.e. '/' .
320  static char GetDefaultFamilySeparator() noexcept;
321  /**
322  * \brief Set the family separator
323  *
324  * Succeeds if the characters is null or a valid character from the ASCII table i.e. from
325  * value 32 (i.e. space) to 126 (i.e. '~'); otherwise, it throws an exception.
326  */
327  void setFamilySeparator(char separator);
328 
329  const char * getDescription() const;
330  void setDescription(const char * description);
331 
332  /**
333  * \brief Returns the string representation of the Config in YAML text form.
334  *
335  * This is typically stored on disk in a file with the extension .ocio.
336  * NB: This does not validate the config. Applications should validate before serializing.
337  */
338  void serialize(std::ostream & os) const;
339 
340  /**
341  * This will produce a hash of the all colorspace definitions, etc. All external references,
342  * such as files used in FileTransforms, etc., will be incorporated into the cacheID. While
343  * the contents of the files are not read, the file system is queried for relevant information
344  * (mtime, inode) so that the config's cacheID will change when the underlying luts are updated.
345  *
346  * If a context is not provided, the current Context will be used.
347  *
348  * If a null context is provided, file references will not be taken into
349  * account (this is essentially a hash of Config::serialize).
350  */
351  const char * getCacheID() const;
352  const char * getCacheID(const ConstContextRcPtr & context) const;
353 
354  //
355  // Resources
356  //
357 
358  ConstContextRcPtr getCurrentContext() const;
359 
360  /// Add (or update) an environment variable with a default value.
361  /// But it removes it if the default value is null.
362  void addEnvironmentVar(const char * name, const char * defaultValue);
363  int getNumEnvironmentVars() const;
364  const char * getEnvironmentVarNameByIndex(int index) const;
365  const char * getEnvironmentVarDefault(const char * name) const;
366  void clearEnvironmentVars();
367 
368  void setEnvironmentMode(EnvironmentMode mode) noexcept;
369  EnvironmentMode getEnvironmentMode() const noexcept;
370  void loadEnvironment() noexcept;
371 
372  const char * getSearchPath() const;
373  /**
374  * \brief Set all search paths as a concatenated string, ':' to separate the
375  * paths.
376  *
377  * See \ref addSearchPath for a more robust and platform-agnostic method of
378  * setting the search paths.
379  */
380  void setSearchPath(const char * path);
381 
382  int getNumSearchPaths() const;
383  /**
384  * Get a search path from the list.
385  *
386  * The paths are in the order they will be searched (that is, highest to
387  * lowest priority).
388  */
389  const char * getSearchPath(int index) const;
390  void clearSearchPaths();
391  /**
392  * \brief Add a single search path to the end of the list.
393  *
394  * Paths may be either absolute or relative. Relative paths are
395  * relative to the working directory. Forward slashes will be
396  * normalized to reverse for Windows. Environment (context) variables
397  * may be used in paths.
398  */
399  void addSearchPath(const char * path);
400 
401  const char * getWorkingDir() const;
402  /**
403  * \brief
404  *
405  * The working directory defaults to the location of the
406  * config file. It is used to convert any relative paths to absolute.
407  * If no search paths have been set, the working directory will be used
408  * as the fallback search path. No environment (context) variables may
409  * be used in the working directory.
410  */
411  void setWorkingDir(const char * dirname);
412 
413  //
414  // ColorSpaces
415  //
416 
417  /**
418  * \brief Get all active color spaces having a specific category
419  * in the order they appear in the config file.
420  *
421  * \note
422  * If the category is null or empty, the method returns
423  * all the active color spaces like \ref Config::getNumColorSpaces
424  * and \ref Config::getColorSpaceNameByIndex do.
425  *
426  * \note
427  * It's worth noticing that the method returns a copy of the
428  * selected color spaces decoupling the result from the config.
429  * Hence, any changes on the config do not affect the existing
430  * color space sets, and vice-versa.
431  */
432  ColorSpaceSetRcPtr getColorSpaces(const char * category) const;
433 
434  /**
435  * \brief Work on the color spaces selected by the reference color space type
436  * and visibility.
437  */
438  int getNumColorSpaces(SearchReferenceSpaceType searchReferenceType,
439  ColorSpaceVisibility visibility) const;
440 
441  /**
442  * \brief Work on the color spaces selected by the reference color space
443  * type and visibility (active or inactive).
444  *
445  * Return empty for invalid index.
446  */
447  const char * getColorSpaceNameByIndex(SearchReferenceSpaceType searchReferenceType,
448  ColorSpaceVisibility visibility, int index) const;
449 
450  /**
451  * \brief Work on the active color spaces only.
452  *
453  * \note
454  * Only works from the list of active color spaces.
455  */
456  int getNumColorSpaces() const;
457 
458  /**
459  * Work on the active color spaces only and return null for invalid index.
460  *
461  * \note
462  * Only works from the list of active color spaces.
463  */
464  const char * getColorSpaceNameByIndex(int index) const;
465 
466  /**
467  * \brief Get an index from the active color spaces only
468  * and return -1 if the name is not found.
469  *
470  * \note
471  * The fcn accepts either a color space name, role name, or alias.
472  * (Color space names take precedence over roles.)
473  */
474  int getIndexForColorSpace(const char * name) const;
475 
476  /**
477  * \brief Get the color space from all the color spaces
478  * (i.e. active and inactive) and return null if the name is not found.
479  *
480  * \note
481  * The fcn accepts either a color space name, role name, or alias.
482  * (Color space names take precedence over roles.)
483  */
484  ConstColorSpaceRcPtr getColorSpace(const char * name) const;
485 
486  /**
487  * Accepts an alias, role name, named transform name, or color space name and returns the
488  * color space name or the named transform name.
489  */
490  const char * getCanonicalName(const char * name) const;
491 
492  /**
493  * \brief Add a color space to the configuration.
494  *
495  * \note
496  * If another color space is already present with the same name,
497  * this will overwrite it. This stores a copy of the specified
498  * color space.
499  * \note
500  * Adding a color space to a \ref Config does not affect any
501  * \ref ColorSpaceSet sets that have already been created.
502  */
503  void addColorSpace(const ConstColorSpaceRcPtr & cs);
504 
505  /**
506  * \brief Remove a color space from the configuration.
507  *
508  * \note
509  * It does not throw an exception. Name must be the canonical name. If a role name or
510  * alias is provided or if the name is not in the config, nothing is done.
511  * \note
512  * Removing a color space from a \ref Config does not affect any
513  * \ref ColorSpaceSet sets that have already been created.
514  */
515  void removeColorSpace(const char * name);
516 
517  /**
518  * Return true if the color space is used by a transform, a role, or a look.
519  *
520  * \note
521  * Name must be the canonical name.
522  */
523  bool isColorSpaceUsed(const char * name) const noexcept;
524 
525  /**
526  * \brief Remove all the color spaces from the configuration.
527  *
528  * \note
529  * Removing color spaces from a \ref Config does not affect
530  * any \ref ColorSpaceSet sets that have already been created.
531  */
532  void clearColorSpaces();
533 
534  /**
535  * \brief Set/get a list of inactive color space or named transform names.
536  *
537  * Notes:
538  * * List can contain color space and/or named transform names.
539  * * The inactive spaces are color spaces that should not appear in application menus.
540  * * These color spaces will still work in Config::getProcessor calls.
541  * * The argument is a comma-delimited string. A null or empty string empties the list.
542  * * The environment variable OCIO_INACTIVE_COLORSPACES may also be used to set the
543  * inactive color space list.
544  * * The env. var. takes precedence over the inactive_colorspaces list in the config file.
545  * * Setting the list via the API takes precedence over either the env. var. or the
546  * config file list.
547  */
548  void setInactiveColorSpaces(const char * inactiveColorSpaces);
549  const char * getInactiveColorSpaces() const;
550 
551  //
552  // Roles
553  //
554 
555  // A role is like an alias for a colorspace. You can query the colorspace
556  // corresponding to a role using the normal getColorSpace fcn.
557 
558  /**
559  * \brief
560  *
561  * \note
562  * Setting the ``colorSpaceName`` name to a null string unsets it.
563  */
564  void setRole(const char * role, const char * colorSpaceName);
565  int getNumRoles() const;
566  /// Return true if the role has been defined.
567  bool hasRole(const char * role) const;
568  /**
569  * \brief Get the role name at index, this will return values
570  * like 'scene_linear', 'compositing_log'.
571  *
572  * Return empty string if index is out of range.
573  */
574  const char * getRoleName(int index) const;
575  /**
576  * \brief Get the role color space at index.
577  *
578  * Return empty string if index is out of range.
579  */
580  const char * getRoleColorSpace(int index) const;
581 
582  /**
583  * \defgroup Methods related to displays and views.
584  * @{
585  */
586 
587  /**
588  * The following methods only manipulate active displays and views. Active
589  * displays and views are defined from an env. variable or from the config file.
590  *
591  * Looks is a potentially comma (or colon) delimited list of lookNames,
592  * Where +/- prefixes are optionally allowed to denote forward/inverse
593  * look specification. (And forward is assumed in the absence of either)
594 
595  * Add shared view (or replace existing one with same name).
596  * Shared views are defined at config level and can be referenced by several
597  * displays. Either provide a view transform and a display color space or
598  * just a color space (and a null view transform). Looks, rule and description
599  * are optional, they can be null or empty.
600  *
601  * Shared views using a view transform may use the token <USE_DISPLAY_NAME>
602  * for the color space (see :c:var:`OCIO_VIEW_USE_DISPLAY_NAME`). In that
603  * case, when the view is referenced in a display, the display color space
604  * that is used will be the one matching the display name. In other words,
605  * the view will be customized based on the display it is used in.
606  * \ref Config::validate will throw if the config does not contain
607  * the matching display color space.
608  */
609  /// Will throw if view or colorSpaceName are null or empty.
610  void addSharedView(const char * view, const char * viewTransformName,
611  const char * colorSpaceName, const char * looks,
612  const char * ruleName, const char * description);
613  /// Remove a shared view. Will throw if the view does not exist.
614  void removeSharedView(const char * view);
615 
616  const char * getDefaultDisplay() const;
617  int getNumDisplays() const;
618  /// Will return "" if the index is invalid.
619  const char * getDisplay(int index) const;
620 
621  const char * getDefaultView(const char * display) const;
622  // Get the default view for a given color space using the viewing rules.
623  // This is the preferred call to use if the color space being viewed is known.
624  const char * getDefaultView(const char * display, const char * colorspaceName) const;
625 
626  /**
627  * Return the number of views attached to the display including the number of
628  * shared views if any. Return 0 if display does not exist.
629  */
630  int getNumViews(const char * display) const;
631  const char * getView(const char * display, int index) const;
632 
633  /**
634  * If the config has ViewingRules, get the number of active Views for this
635  * colorspace. (If there are no rules, it returns all of them.)
636  */
637  int getNumViews(const char * display, const char * colorspaceName) const;
638  const char * getView(const char * display, const char * colorspaceName, int index) const;
639 
640  /**
641  * Returns the view_transform attribute of the (display, view) pair. View can
642  * be a shared view of the display. If display is null or empty, config shared views are used.
643  */
644  const char * getDisplayViewTransformName(const char * display, const char * view) const;
645  /**
646  * Returns the colorspace attribute of the (display, view) pair.
647  * (Note that this may be either a color space or a display color space.)
648  */
649  const char * getDisplayViewColorSpaceName(const char * display, const char * view) const;
650  /// Returns the looks attribute of a (display, view) pair.
651  const char * getDisplayViewLooks(const char * display, const char * view) const;
652  /// Returns the rule attribute of a (display, view) pair.
653  const char * getDisplayViewRule(const char * display, const char * view) const noexcept;
654  /// Returns the description attribute of a (display, view) pair.
655  const char * getDisplayViewDescription(const char * display, const char * view) const noexcept;
656 
657  /**
658  * For the (display, view) pair, specify which color space and look to use.
659  * If a look is not desired, then just pass a null or empty string.
660  */
661  void addDisplayView(const char * display, const char * view,
662  const char * colorSpaceName, const char * looks);
663 
664  /**
665  * \brief
666  *
667  * For the (display, view) pair, specify the color space or alternatively
668  * specify the view transform and display color space. The looks, viewing rule, and
669  * description are optional. Pass a null or empty string for any optional arguments.
670  * If the view already exists, it is replaced.
671  *
672  * Will throw if:
673  * * Display, view or colorSpace are null or empty.
674  * * Display already has a shared view with the same name.
675  */
676  void addDisplayView(const char * display, const char * view, const char * viewTransformName,
677  const char * colorSpaceName, const char * looks,
678  const char * ruleName, const char * description);
679 
680  /**
681  * \brief Add a (reference to a) shared view to a display.
682  *
683  * The shared view must be part of the config. See \ref Config::addSharedView
684  *
685  * This will throw if:
686  * * Display or view are null or empty.
687  * * Display already has a view (shared or not) with the same name.
688  */
689  void addDisplaySharedView(const char * display, const char * sharedView);
690 
691  /**
692  * \brief Remove the view and the display if no more views.
693  *
694  * It does not remove the associated color space. If the view name is a
695  * shared view, it only removes the reference to the view from the display
696  * but the shared view, remains in the config.
697  *
698  * Will throw if the view does not exist.
699  */
700  void removeDisplayView(const char * display, const char * view);
701  /// Clear all the displays.
702  void clearDisplays();
703 
704  /** @} */
705 
706  /**
707  * \defgroup Methods related to the Virtual Display.
708  * @{
709  *
710  * ... (See descriptions for the non-virtual methods above.)
711  *
712  * The virtual display is the way to incorporate the ICC monitor profile for a user's display
713  * into OCIO. The views that are defined for the virtual display are the views that are used to
714  * create a new display for an ICC profile. They serve as a kind of template that lets OCIO
715  * know how to build the new display.
716  *
717  * Typically the views will define a View Transform and set the colorSpaceName to
718  * "<USE_DISPLAY_NAME>" so that it will use the display color space with the same name as the
719  * display, in this case corresponding to the ICC profile.
720  *
721  */
722 
723  void addVirtualDisplayView(const char * view,
724  const char * viewTransformName,
725  const char * colorSpaceName,
726  const char * looks,
727  const char * ruleName,
728  const char * description);
729 
730  void addVirtualDisplaySharedView(const char * sharedView);
731 
732  /// Get the number of views associated to the virtual display.
733  int getVirtualDisplayNumViews(ViewType type) const noexcept;
734  /// Get the view name at a specific index.
735  const char * getVirtualDisplayView(ViewType type, int index) const noexcept;
736 
737  const char * getVirtualDisplayViewTransformName(const char * view) const noexcept;
738  const char * getVirtualDisplayViewColorSpaceName(const char * view) const noexcept;
739  const char * getVirtualDisplayViewLooks(const char * view) const noexcept;
740  const char * getVirtualDisplayViewRule(const char * view) const noexcept;
741  const char * getVirtualDisplayViewDescription(const char * view) const noexcept;
742 
743  /// Remove the view from the virtual display.
744  void removeVirtualDisplayView(const char * view) noexcept;
745 
746  /// Clear the virtual display.
747  void clearVirtualDisplay() noexcept;
748 
749  /**
750  * \brief Instantiate a new display from a virtual display, using the monitor name.
751  *
752  * This method uses the virtual display to create an actual display for the given monitorName.
753  * The new display will receive the views from the virtual display.
754  *
755  * After the ICC profile is read, a display name will be created by combining the description
756  * text from the profile with the monitorName obtained from the OS. Use the SystemMonitors class
757  * to obtain the list of monitorName strings for the displays connected to the computer.
758  *
759  * A new display color space will also be created using the display name. It will have a
760  * from_display_reference transform that is a FileTransform pointing to the ICC profile.
761  *
762  * Any instantiated display color spaces for a virtual display are intended to be temporary
763  * (i.e. last as long as the current session). By default, they are not saved when writing a
764  * config file. If there is a need to make it a permanent color space, it may be desirable to
765  * copy the ICC profile somewhere under the config search_path.
766  *
767  * Will throw if the config does not have a virtual display or if the monitorName does not exist.
768  *
769  * If there is already a display or a display color space with the name monitorName, it will be
770  * replaced/updated.
771  *
772  * Returns the index of the display.
773  */
774  int instantiateDisplayFromMonitorName(const char * monitorName);
775 
776  /**
777  * \brief Instantiate a new display from a virtual display, using an ICC profile.
778  *
779  * On platforms such as Linux, where the SystemMonitors class is not able to obtain a list of
780  * ICC profiles from the OS, this method may be used to manually specify a path to an ICC profile.
781  *
782  * Will throw if the virtual display definition is missing from the config.
783  *
784  * Returns the index of the display.
785  */
786  int instantiateDisplayFromICCProfile(const char * ICCProfileFilepath);
787 
788  /** @} */
789 
790  /**
791  * \brief
792  *
793  * $OCIO_ACTIVE_DISPLAYS envvar can, at runtime, optionally override the
794  * allowed displays. It is a comma or colon delimited list. Active displays
795  * that are not in the specified profile will be ignored, and the
796  * left-most defined display will be the default.
797  *
798  * Comma-delimited list of names to filter and order the active displays.
799  *
800  * \note
801  * The setter does not override the envvar. The getter does not take into
802  * account the envvar value and thus may not represent what the user is seeing.
803  */
804  void setActiveDisplays(const char * displays);
805  const char * getActiveDisplays() const;
806 
807  /**
808  * \brief
809  *
810  * $OCIO_ACTIVE_VIEWS envvar can, at runtime, optionally override the allowed views.
811  * It is a comma or colon delimited list.
812  * Active views that are not in the specified profile will be ignored, and the
813  * left-most defined view will be the default.
814  *
815  * Comma-delimited list of names to filter and order the active views.
816  *
817  * \note
818  * The setter does not override the envvar. The getter does not take
819  * into account the envvar value and thus may not represent what the
820  * user is seeing.
821  */
822  void setActiveViews(const char * views);
823  const char * getActiveViews() const;
824 
825  /// Get all displays in the config, ignoring the active_displays list.
826  int getNumDisplaysAll() const noexcept;
827  const char * getDisplayAll(int index) const noexcept;
828  int getDisplayAllByName(const char *) const noexcept;
829  /**
830  * Will be true for a display that was instantiated from a virtual display. These displays are
831  * intended to be temporary (i.e. for the current session) and are not saved to a config file.
832  */
833  bool isDisplayTemporary(int index) const noexcept;
834 
835  /**
836  * Get either the shared or display-defined views for a display. The
837  * active_views list is ignored. Passing a null or empty display (with type=VIEW_SHARED)
838  * returns the contents of the shared_views section of the config. Return 0 if display
839  * does not exist.
840  */
841  int getNumViews(ViewType type, const char * display) const;
842  const char * getView(ViewType type, const char * display, int index) const;
843 
844  //
845  // Viewing Rules
846  //
847 
848  /// Get read-only version of the viewing rules.
849  ConstViewingRulesRcPtr getViewingRules() const noexcept;
850 
851  /**
852  * \brief Set viewing rules.
853  *
854  * \note
855  * The argument is cloned.
856  */
857  void setViewingRules(ConstViewingRulesRcPtr viewingRules);
858 
859  //
860  // Luma
861  // ^^^^
862 
863  /**
864  * \brief Get the default coefficients for computing luma.
865  *
866  * \note
867  * There is no "1 size fits all" set of luma coefficients. (The
868  * values are typically different for each colorspace, and the
869  * application of them may be nonsensical depending on the
870  * intensity coding anyways). Thus, the 'right' answer is to make
871  * these functions on the ColorSpace class. However, it's
872  * often useful to have a config-wide default so here it is. We will
873  * add the colorspace specific luma call if/when another client is
874  * interesting in using it.
875  */
876  void getDefaultLumaCoefs(double * rgb) const;
877  /// These should be normalized (sum to 1.0 exactly).
878  void setDefaultLumaCoefs(const double * rgb);
879 
880 
881  //
882  // Look
883  //
884 
885  // Manager per-shot look settings.
886 
887  ConstLookRcPtr getLook(const char * name) const;
888 
889  int getNumLooks() const;
890 
891  const char * getLookNameByIndex(int index) const;
892 
893  void addLook(const ConstLookRcPtr & look);
894 
895  void clearLooks();
896 
897 
898  //
899  // View Transforms
900  //
901 
902  // ViewTransform objects are used with the display reference space.
903 
904  int getNumViewTransforms() const noexcept;
905 
906  ConstViewTransformRcPtr getViewTransform(const char * name) const noexcept;
907 
908  const char * getViewTransformNameByIndex(int i) const noexcept;
909 
910  void addViewTransform(const ConstViewTransformRcPtr & viewTransform);
911 
912  /**
913  * \brief
914  *
915  * This view transform is the one that will be used by default if a ColorSpaceTransform is
916  * needed between a scene-referred and display-referred color space. The config author may
917  * specify a transform to use via the default_view_transform entry in the config. If that is
918  * not present, or does not return a valid view transform from the scene-referred connection
919  * space, the fall-back is to use the first valid view transform in the config. Returns a
920  * null ConstTransformRcPtr if there isn't one.
921  */
922  ConstViewTransformRcPtr getDefaultSceneToDisplayViewTransform() const;
923 
924  /**
925  * Get or set the default_view_transform string from the config.
926  *
927  * Note that if this is not the name of a valid view transform from the scene-referred
928  * connection space, it will be ignored.
929  */
930  const char * getDefaultViewTransformName() const noexcept;
931  void setDefaultViewTransformName(const char * defaultName) noexcept;
932 
933 
934  void clearViewTransforms();
935 
936  /**
937  * \defgroup Methods related to named transforms.
938  * @{
939  */
940 
941  /**
942  * \brief Work on the named transforms selected by visibility.
943  */
944  int getNumNamedTransforms(NamedTransformVisibility visibility) const noexcept;
945 
946  /**
947  * \brief Work on the named transforms selected by visibility (active or inactive).
948  *
949  * Return an empty string for invalid index.
950  */
951  const char * getNamedTransformNameByIndex(NamedTransformVisibility visibility,
952  int index) const noexcept;
953 
954  /// Work on the active named transforms only.
955  int getNumNamedTransforms() const noexcept;
956 
957  /// Work on the active named transforms only and return an empty string for invalid index.
958  const char * getNamedTransformNameByIndex(int index) const noexcept;
959 
960  /// Get an index from the active named transforms only and return -1 if the name is not found.
961  int getIndexForNamedTransform(const char * name) const noexcept;
962 
963  /**
964  * \brief Get the named transform from all the named transforms (i.e. active and inactive) and
965  * return null if the name is not found.
966  */
967  ConstNamedTransformRcPtr getNamedTransform(const char * name) const noexcept;
968 
969  /**
970  * \brief Add or replace named transform.
971  *
972  * \note
973  * Throws if namedTransform is null, name is missing, or no transform is set. Also throws
974  * if the name or the aliases conflict with names or aliases already in the config.
975  */
976  void addNamedTransform(const ConstNamedTransformRcPtr & namedTransform);
977 
978  /// Clear all named transforms.
979  void clearNamedTransforms();
980 
981  /** @} */
982 
983  //
984  // File Rules
985  //
986 
987  /// Get read-only version of the file rules.
988  ConstFileRulesRcPtr getFileRules() const noexcept;
989 
990  /**
991  * \brief Set file rules.
992  *
993  * \note
994  * The argument is cloned.
995  */
996  void setFileRules(ConstFileRulesRcPtr fileRules);
997 
998  /// Get the color space of the first rule that matched filePath. (For v1 configs, this is
999  /// equivalent to calling parseColorSpaceFromString with strictparsing set to false.)
1000  const char * getColorSpaceFromFilepath(const char * filePath) const;
1001 
1002  /**
1003  * Most applications will use the preceding method, but this method may be
1004  * used for applications that want to know which was the highest priority rule to match
1005  * filePath. \ref FileRules::getNumCustomKeys and custom keys methods
1006  * may then be used to get additional information about the matching rule.
1007  */
1008  const char * getColorSpaceFromFilepath(const char * filePath, size_t & ruleIndex) const;
1009 
1010  /**
1011  * \brief
1012  *
1013  * Returns true if the only rule matched by filePath is the default rule.
1014  * This is a convenience method for applications that want to require the user to manually
1015  * choose a color space when strictParsing is true and no other rules match.
1016  */
1017  bool filepathOnlyMatchesDefaultRule(const char * filePath) const;
1018 
1019  /**
1020  * Given the specified string, get the longest, right-most, colorspace substring that
1021  * appears.
1022  *
1023  * * If strict parsing is enabled, and no color space is found, return
1024  * an empty string.
1025  * * If strict parsing is disabled, return ROLE_DEFAULT (if defined).
1026  * * If the default role is not defined, return an empty string.
1027  */
1028  OCIO_DEPRECATED("This was marked as deprecated starting in v2.0, please use Config::getColorSpaceFromFilepath().")
1029  const char * parseColorSpaceFromString(const char * str) const;
1030 
1031  bool isStrictParsingEnabled() const;
1032  void setStrictParsingEnabled(bool enabled);
1033 
1034  //
1035  // Processors
1036  //
1037 
1038  // Create a Processor to assemble a transformation between two
1039  // color spaces. It may then be used to create a CPUProcessor
1040  // or GPUProcessor to process/convert pixels.
1041 
1042  /// Get the processor to apply a ColorSpaceTransform from a source to a destination
1043  /// color space.
1044  ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
1045  const ConstColorSpaceRcPtr & srcColorSpace,
1046  const ConstColorSpaceRcPtr & dstColorSpace) const;
1047  ConstProcessorRcPtr getProcessor(const ConstColorSpaceRcPtr & srcColorSpace,
1048  const ConstColorSpaceRcPtr & dstColorSpace) const;
1049 
1050  /**
1051  * \brief
1052  *
1053  * \note
1054  * Names can be colorspace name, role name, or a combination of both.
1055  */
1056  ConstProcessorRcPtr getProcessor(const char * srcColorSpaceName,
1057  const char * dstColorSpaceName) const;
1058  ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
1059  const char * srcColorSpaceName,
1060  const char * dstColorSpaceName) const;
1061 
1062  /// Get the processor to apply a DisplayViewTransform for a display and view. Refer to the
1063  /// Display/View Registration section above for more info on the display and view arguments.
1064  ConstProcessorRcPtr getProcessor(const char * srcColorSpaceName,
1065  const char * display,
1066  const char * view,
1068 
1069  ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
1070  const char * srcColorSpaceName,
1071  const char * display,
1072  const char * view,
1073  TransformDirection direction) const;
1074 
1075  /**
1076  * \brief Get the processor for the specified transform.
1077  *
1078  * Not often needed, but will allow for the re-use of atomic OCIO
1079  * functionality (such as to apply an individual LUT file).
1080  */
1081  ConstProcessorRcPtr getProcessor(const ConstTransformRcPtr & transform) const;
1082  ConstProcessorRcPtr getProcessor(const ConstTransformRcPtr & transform,
1083  TransformDirection direction) const;
1084  ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
1085  const ConstTransformRcPtr & transform,
1086  TransformDirection direction) const;
1087 
1088  /**
1089  * \brief Get a processor to convert between color spaces in two separate
1090  * configs.
1091  *
1092  * This relies on both configs having the aces_interchange role (when srcName
1093  * is scene-referred) or the role cie_xyz_d65_interchange (when srcName is
1094  * display-referred) defined. An exception is thrown if that is not the case.
1095  */
1096  static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstConfigRcPtr & srcConfig,
1097  const char * srcColorSpaceName,
1098  const ConstConfigRcPtr & dstConfig,
1099  const char * dstColorSpaceName);
1100  static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstContextRcPtr & srcContext,
1101  const ConstConfigRcPtr & srcConfig,
1102  const char * srcColorSpaceName,
1103  const ConstContextRcPtr & dstContext,
1104  const ConstConfigRcPtr & dstConfig,
1105  const char * dstColorSpaceName);
1106 
1107  /**
1108  * The srcInterchangeName and dstInterchangeName must refer to a pair of
1109  * color spaces in the two configs that are the same. A role name may also be used.
1110  */
1111  static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstConfigRcPtr & srcConfig,
1112  const char * srcColorSpaceName,
1113  const char * srcInterchangeName,
1114  const ConstConfigRcPtr & dstConfig,
1115  const char * dstColorSpaceName,
1116  const char * dstInterchangeName);
1117 
1118  static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstContextRcPtr & srcContext,
1119  const ConstConfigRcPtr & srcConfig,
1120  const char * srcColorSpaceName,
1121  const char * srcInterchangeName,
1122  const ConstContextRcPtr & dstContext,
1123  const ConstConfigRcPtr & dstConfig,
1124  const char * dstColorSpaceName,
1125  const char * dstInterchangeName);
1126 
1127  Config(const Config &) = delete;
1128  Config& operator= (const Config &) = delete;
1129 
1130  /// Do not use (needed only for pybind11).
1131  ~Config();
1132 
1133  /// Control the caching of processors in the config instance. By default, caching is on.
1134  /// The flags allow turning caching off entirely or only turning it off if dynamic
1135  /// properties are being used by the processor.
1136  void setProcessorCacheFlags(ProcessorCacheFlags flags) noexcept;
1137 
1138 private:
1139  Config();
1140 
1141  static void deleter(Config* c);
1142 
1143  class Impl;
1144  Impl * m_impl;
1145  Impl * getImpl() { return m_impl; }
1146  const Impl * getImpl() const { return m_impl; }
1147 };
1148 
1149 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Config&);
1150 
1151 
1152 /**
1153  * \brief
1154  * The File Rules are a set of filepath to color space mappings that are evaluated
1155  * from first to last. The first rule to match is what determines which color space is
1156  * returned. There are four types of rules available. Each rule type has a name key that may
1157  * be used by applications to refer to that rule. Name values must be unique i.e. using a
1158  * case insensitive comparison. The other keys depend on the rule type:
1159  *
1160  * * *Basic Rule*: This is the basic rule type that uses Unix glob style pattern matching and
1161  * is thus very easy to use. It contains the keys:
1162  * * name: Name of the rule
1163  * * colorspace: Color space name to be returned.
1164  * * pattern: Glob pattern to be used for the main part of the name/path.
1165  * * extension: Glob pattern to be used for the file extension. Note that if glob tokens
1166  * are not used, the extension will be used in a non-case-sensitive way by default.
1167  *
1168  * * *Regex Rule*: This is similar to the basic rule but allows additional capabilities for
1169  * power-users. It contains the keys:
1170  * * name: Name of the rule
1171  * * colorspace: Color space name to be returned.
1172  * * regex: Regular expression to be evaluated.
1173  *
1174  * * *OCIO v1 style Rule*: This rule allows the use of the OCIO v1 style, where the string
1175  * is searched for color space names from the config. This rule may occur 0 or 1 times
1176  * in the list. The position in the list prioritizes it with respect to the other rules.
1177  * StrictParsing is not used. If no color space is found in the path, the rule will not
1178  * match and the next rule will be considered.
1179  * see \ref insertPathSearchRule.
1180  * It has the key:
1181  * * name: Must be "ColorSpaceNamePathSearch".
1182  *
1183  * * *Default Rule*: The file_rules must always end with this rule. If no prior rules match,
1184  * this rule specifies the color space applications will use.
1185  * see \ref setDefaultRuleColorSpace.
1186  * It has the keys:
1187  * * name: must be "Default".
1188  * * colorspace : Color space name to be returned.
1189  *
1190  * Custom string keys and associated string values may be used to convey app or
1191  * workflow-specific information, e.g. whether the color space should be left as is
1192  * or converted into a working space.
1193  *
1194  * Getters and setters are using the rule position, they will throw if the position is not
1195  * valid. If the rule at the specified position does not implement the requested property
1196  * getter will return NULL and setter will throw.
1197  *
1198  * When loading a v1 config, a set of FileRules are created with ColorSpaceNamePathSearch followed
1199  * by the Default rule pointing to the default role. This allows getColorSpaceFromFilepath to emulate
1200  * OCIO v1 code that used parseColorSpaceFromString with strictparsing set to false.
1201  */
1202 
1204 {
1205 public:
1206 
1207  /// Reserved rule name for the default rule.
1208  static const char * DefaultRuleName;
1209  /// Reserved rule name for the file path search rule \see FileRules::insertPathSearchRule.
1210  static const char * FilePathSearchRuleName;
1211 
1212  /**
1213  * Creates FileRules for a Config. File rules will contain the default rule
1214  * using the default role. The default rule cannot be removed.
1215  */
1216  static FileRulesRcPtr Create();
1217 
1218  /// The method clones the content decoupling the two instances.
1219  FileRulesRcPtr createEditableCopy() const;
1220 
1221  /// Does include default rule. Result will be at least 1.
1222  size_t getNumEntries() const noexcept;
1223 
1224  /// Get the index from the rule name.
1225  size_t getIndexForRule(const char * ruleName) const;
1226 
1227  /// Get name of the rule.
1228  const char * getName(size_t ruleIndex) const;
1229 
1230  /// Setting pattern will erase regex.
1231  const char * getPattern(size_t ruleIndex) const;
1232  void setPattern(size_t ruleIndex, const char * pattern);
1233 
1234  /// Setting extension will erase regex.
1235  const char * getExtension(size_t ruleIndex) const;
1236  void setExtension(size_t ruleIndex, const char * extension);
1237 
1238  /// Setting a regex will erase pattern & extension.
1239  const char * getRegex(size_t ruleIndex) const;
1240  void setRegex(size_t ruleIndex, const char * regex);
1241 
1242  /// Set the rule's color space (may also be a role).
1243  const char * getColorSpace(size_t ruleIndex) const;
1244  void setColorSpace(size_t ruleIndex, const char * colorSpace);
1245 
1246  /// Get number of key/value pairs.
1247  size_t getNumCustomKeys(size_t ruleIndex) const;
1248  /// Get name of key.
1249  const char * getCustomKeyName(size_t ruleIndex, size_t key) const;
1250  /// Get value for the key.
1251  const char * getCustomKeyValue(size_t ruleIndex, size_t key) const;
1252  /**
1253  * Adds a key/value or replace value if key exists. Setting a NULL or an
1254  * empty value will erase the key.
1255  */
1256  void setCustomKey(size_t ruleIndex, const char * key, const char * value);
1257 
1258  /**
1259  * \brief Insert a rule at a given ruleIndex.
1260  *
1261  * Rule currently at ruleIndex will be pushed to index: ruleIndex + 1.
1262  * Name must be unique.
1263  * - "Default" is a reserved name for the default rule. The default rule is automatically
1264  * added and can't be removed. (see \ref FileRules::setDefaultRuleColorSpace ).
1265  * - "ColorSpaceNamePathSearch" is also a reserved name
1266  * (see \ref FileRules::insertPathSearchRule ).
1267  *
1268  * Will throw if pattern, extension or regex is a null or empty string.
1269  *
1270  * Will throw if ruleIndex is not less than \ref FileRules::getNumEntries .
1271  */
1272  void insertRule(size_t ruleIndex, const char * name, const char * colorSpace,
1273  const char * pattern, const char * extension);
1274  void insertRule(size_t ruleIndex, const char * name, const char * colorSpace,
1275  const char * regex);
1276  /**
1277  * \brief Helper function to insert a rule.
1278  *
1279  * Uses \ref Config:parseColorSpaceFromString to search the path for any of
1280  * the color spaces named in the config (as per OCIO v1).
1281  */
1282  void insertPathSearchRule(size_t ruleIndex);
1283  /// Helper function to set the color space for the default rule.
1284  void setDefaultRuleColorSpace(const char * colorSpace);
1285 
1286  /**
1287  * \brief
1288  *
1289  * \note
1290  * Default rule can't be removed.
1291  * Will throw if ruleIndex + 1 is not less than \ref FileRules::getNumEntries .
1292  */
1293  void removeRule(size_t ruleIndex);
1294 
1295  /// Move a rule closer to the start of the list by one position.
1296  void increaseRulePriority(size_t ruleIndex);
1297 
1298  /// Move a rule closer to the end of the list by one position.
1299  void decreaseRulePriority(size_t ruleIndex);
1300 
1301  /**
1302  * Check if there is only the default rule using default role and no custom key. This is the
1303  * default FileRules state when creating a new config.
1304  */
1305  bool isDefault() const noexcept;
1306 
1307  FileRules(const FileRules &) = delete;
1308  FileRules & operator= (const FileRules &) = delete;
1309 
1310  /// Do not use (needed only for pybind11).
1311  virtual ~FileRules();
1312 
1313 private:
1314  FileRules();
1315 
1316  static void deleter(FileRules* c);
1317 
1318  friend class Config;
1319 
1320  class Impl;
1321  Impl * m_impl;
1322  Impl * getImpl() { return m_impl; }
1323  const Impl * getImpl() const { return m_impl; }
1324 };
1325 
1326 extern OCIOEXPORT std::ostream & operator<< (std::ostream &, const FileRules &);
1327 
1328 
1329 
1330 /**
1331  * ViewingRules
1332  *
1333  * Viewing Rules allow config authors to filter the list of views an application should offer
1334  * based on the color space of an image. For example, a config may define a large number of
1335  * views but not all of them may be appropriate for use with all color spaces. E.g., some views
1336  * may be intended for use with scene-linear color space encodings and others with video color
1337  * space encodings.
1338  *
1339  * Each rule has a name key for applications to refer to the rule. Name values must be unique
1340  * (using case insensitive comparison). Viewing Rules may also have the following keys:
1341  *
1342  * * colorspaces: Either a single colorspace name or a list of names.
1343  *
1344  * * encodings: One or more strings to be found in the colorspace's encoding attribute.
1345  * Either this attribute or colorspaces must be present, but not both.
1346  *
1347  * * custom : Allows arbitrary key / value string pairs, similar to FileRules.
1348  *
1349  * Getters and setters are using the rule position, they will throw if the position is not
1350  * valid.
1351 */
1353 {
1354 public:
1355  /// Creates ViewingRules for a Config.
1356  static ViewingRulesRcPtr Create();
1357 
1358  /// The method clones the content decoupling the two instances.
1359  ViewingRulesRcPtr createEditableCopy() const;
1360 
1361  size_t getNumEntries() const noexcept;
1362 
1363  /**
1364  * Get the index from the rule name. Will throw if there is no rule named
1365  * ruleName.
1366  */
1367  size_t getIndexForRule(const char * ruleName) const;
1368 
1369  /// Get name of the rule. Will throw if ruleIndex is invalid.
1370  const char * getName(size_t ruleIndex) const;
1371 
1372  /// Get number of colorspaces. Will throw if ruleIndex is invalid.
1373  size_t getNumColorSpaces(size_t ruleIndex) const;
1374  /// Get colorspace name. Will throw if ruleIndex or colorSpaceIndex is invalid.
1375  const char * getColorSpace(size_t ruleIndex, size_t colorSpaceIndex) const;
1376  /**
1377  * \brief
1378  *
1379  * Add colorspace name. Will throw if:
1380  * * RuleIndex is invalid.
1381  * * \ref ViewingRules::getNumEncodings is not 0.
1382  */
1383  void addColorSpace(size_t ruleIndex, const char * colorSpace);
1384  /// Remove colorspace. Will throw if ruleIndex or colorSpaceIndex is invalid.
1385  void removeColorSpace(size_t ruleIndex, size_t colorSpaceIndex);
1386 
1387  /// Get number of encodings. Will throw if ruleIndex is invalid.
1388  size_t getNumEncodings(size_t ruleIndex) const;
1389  /// Get encoding name. Will throw if ruleIndex or encodingIndex is invalid.
1390  const char * getEncoding(size_t ruleIndex, size_t encodingIndex) const;
1391 
1392  /**
1393  * \brief
1394  * Add encoding name. Will throw if:
1395  * * RuleIndex is invalid.
1396  * * \ref ViewingRules::getNumColorSpaces is not 0.
1397  */
1398  void addEncoding(size_t ruleIndex, const char * encoding);
1399  /// Remove encoding. Will throw if ruleIndex or encodingIndex is invalid.
1400  void removeEncoding(size_t ruleIndex, size_t encodingIndex);
1401 
1402  /// Get number of key/value pairs. Will throw if ruleIndex is invalid.
1403  size_t getNumCustomKeys(size_t ruleIndex) const;
1404  /// Get name of key. Will throw if ruleIndex or keyIndex is invalid.
1405  const char * getCustomKeyName(size_t ruleIndex, size_t keyIndex) const;
1406  /// Get value for the key. Will throw if ruleIndex or keyIndex is invalid.
1407  const char * getCustomKeyValue(size_t ruleIndex, size_t keyIndex) const;
1408  /**
1409  * Adds a key/value or replace value if key exists. Setting a NULL or an
1410  * empty value will erase the key. Will throw if ruleIndex is invalid.
1411  */
1412  void setCustomKey(size_t ruleIndex, const char * key, const char * value);
1413 
1414  /**
1415  * \brief Insert a rule at a given ruleIndex.
1416  *
1417  * Rule currently at ruleIndex will be pushed to index: ruleIndex + 1. If ruleIndex is
1418  * \ref ViewingRules::getNumEntries, a new rule will be added at the end. Will throw if:
1419  * * RuleIndex is invalid (must be less than or equal to
1420  * \ref ViewingRules::getNumEntries).
1421  * * RuleName already exists.
1422  */
1423  void insertRule(size_t ruleIndex, const char * ruleName);
1424 
1425  /// Remove a rule. Throws if ruleIndex is not valid.
1426  void removeRule(size_t ruleIndex);
1427 
1428  ViewingRules(const ViewingRules &) = delete;
1429  ViewingRules & operator= (const ViewingRules &) = delete;
1430  /// Do not use (needed only for pybind11).
1431  virtual ~ViewingRules();
1432 
1433 private:
1434  ViewingRules();
1435 
1436  static void deleter(ViewingRules* c);
1437 
1438  friend class Config;
1439 
1440  class Impl;
1441  Impl * m_impl;
1442  Impl * getImpl() { return m_impl; }
1443  const Impl * getImpl() const { return m_impl; }
1444 };
1445 
1446 extern OCIOEXPORT std::ostream & operator<< (std::ostream &, const ViewingRules &);
1447 
1448 //
1449 // ColorSpace
1450 //
1451 /**
1452  * The *ColorSpace* is the state of an image with respect to colorimetry
1453  * and color encoding. Transforming images between different
1454  * *ColorSpaces* is the primary motivation for this library.
1455  *
1456  * While a complete discussion of color spaces is beyond the scope of
1457  * header documentation, traditional uses would be to have *ColorSpaces*
1458  * corresponding to: physical capture devices (known cameras, scanners),
1459  * and internal 'convenience' spaces (such as scene linear, logarithmic).
1460  *
1461  * *ColorSpaces* are specific to a particular image precision (float32,
1462  * uint8, etc.), and the set of ColorSpaces that provide equivalent mappings
1463  * (at different precisions) are referred to as a 'family'.
1464  */
1466 {
1467 public:
1468  static ColorSpaceRcPtr Create();
1469 
1470  static ColorSpaceRcPtr Create(ReferenceSpaceType referenceSpace);
1471 
1472  ColorSpaceRcPtr createEditableCopy() const;
1473 
1474  const char * getName() const noexcept;
1475  /// If the name is already an alias, that alias is removed.
1476  void setName(const char * name) noexcept;
1477 
1478  size_t getNumAliases() const noexcept;
1479  /// Return empty string if idx is out of range.
1480  const char * getAlias(size_t idx) const noexcept;
1481  /**
1482  * Add an alias for the color space name (the aliases may be used as a synonym for the
1483  * name). Nothing will be added if the alias is already the color space name, one of its
1484  * aliases, or the argument is null. The aliases must not conflict with existing roles,
1485  * color space names, named transform names, or other aliases. This is verified when
1486  * adding the color space to the config.
1487  */
1488  void addAlias(const char * alias) noexcept;
1489  /// Does nothing if alias is not present.
1490  void removeAlias(const char * alias) noexcept;
1491  void clearAliases() noexcept;
1492 
1493  /**
1494  * Get the family, for use in user interfaces (optional)
1495  * The family string could use a '/' separator to indicate levels to be used
1496  * by hierarchical menus.
1497  */
1498  const char * getFamily() const noexcept;
1499  /// Set the family, for use in user interfaces (optional)
1500  void setFamily(const char * family);
1501 
1502  /**
1503  * Get the ColorSpace group name (used for equality comparisons)
1504  * This allows no-op transforms between different colorspaces.
1505  * If an equalityGroup is not defined (an empty string), it will be considered
1506  * unique (i.e., it will not compare as equal to other ColorSpaces with an
1507  * empty equality group). This is often, though not always, set to the
1508  * same value as 'family'.
1509  */
1510  const char * getEqualityGroup() const noexcept;
1511  void setEqualityGroup(const char * equalityGroup);
1512 
1513  const char * getDescription() const noexcept;
1514  void setDescription(const char * description);
1515 
1516  BitDepth getBitDepth() const noexcept;
1517  void setBitDepth(BitDepth bitDepth);
1518 
1519  /// A display color space will use the display-referred reference space.
1520  ReferenceSpaceType getReferenceSpaceType() const noexcept;
1521 
1522  //
1523  // Categories
1524  //
1525 
1526  /**
1527  * A category is used to allow applications to filter the list of color spaces
1528  * they display in menus based on what that color space is used for.
1529  *
1530  * Here is an example config entry that could appear under a ColorSpace:
1531  *
1532  * \code{.yaml}
1533  * categories: [ file-io, working-space, basic-3d ]
1534  * \endcode
1535  *
1536  * The example contains three categories: 'file-io', 'working-space' and 'basic-3d'.
1537  *
1538  * \note
1539  * Category strings are not case-sensitive and the order is not significant.
1540  *
1541  * There is no limit imposed on length or number. Although users may add their own categories,
1542  * the strings will typically come from a fixed set listed in the documentation (similar to
1543  * roles).
1544  */
1545  /// Return true if the category is present.
1546  bool hasCategory(const char * category) const;
1547  /**
1548  * \brief Add a single category.
1549  *
1550  * \note
1551  * Will do nothing if the category already exists.
1552  */
1553  void addCategory(const char * category);
1554  /**
1555  * \brief Remove a category.
1556  *
1557  * \note
1558  * Will do nothing if the category is missing.
1559  */
1560  void removeCategory(const char * category);
1561  /// Get the number of categories.
1562  int getNumCategories() const;
1563  /**
1564  * \brief Return the category name using its index
1565  *
1566  * \note
1567  * Will be null if the index is invalid.
1568  */
1569  const char * getCategory(int index) const;
1570  /// Clear all the categories.
1571  void clearCategories();
1572 
1573  /**
1574  * *Encodings*
1575  *
1576  * It is sometimes useful for applications to group color spaces based on how the color values
1577  * are digitally encoded. For example, images in scene-linear, logarithmic, video, and data
1578  * color spaces could have different default views. Unlike the Family and EqualityGroup
1579  * attributes of a color space, the list of Encodings is predefined in the OCIO documentation
1580  * (rather than being config-specific) to make it easier for applications to utilize.
1581  *
1582  * Here is an example config entry that could appear under a ColorSpace:
1583  *
1584  * \code{.yaml}
1585  * encoding: scene-linear
1586  * \endcode
1587  *
1588  * Encoding strings are not case-sensitive. Although users may add their own encodings, the
1589  * strings will typically come from a fixed set listed in the documentation (similar to roles).
1590  */
1591  const char * getEncoding() const noexcept;
1592  void setEncoding(const char * encoding);
1593 
1594  /**
1595  * *Data*
1596  *
1597  * ColorSpaces that are data are treated a bit special. Basically, any colorspace transforms
1598  * you try to apply to them are ignored. (Think of applying a gamut mapping transform to an
1599  * ID pass). However, the setDataBypass method on ColorSpaceTransform and DisplayViewTransform
1600  * allow applications to process data when necessary. (Think of sending mattes to an HDR
1601  * monitor.)
1602  *
1603  * This is traditionally used for pixel data that represents non-color
1604  * pixel data, such as normals, point positions, ID information, etc.
1605  */
1606  bool isData() const noexcept;
1607  void setIsData(bool isData) noexcept;
1608 
1609  /**
1610  * *Allocation*
1611  *
1612  * If this colorspace needs to be transferred to a limited dynamic
1613  * range coding space (such as during display with a GPU path), use this
1614  * allocation to maximize bit efficiency.
1615  */
1616  Allocation getAllocation() const noexcept;
1617  void setAllocation(Allocation allocation) noexcept;
1618 
1619  /**
1620  * Specify the optional variable values to configure the allocation.
1621  * If no variables are specified, the defaults are used.
1622  *
1623  * ALLOCATION_UNIFORM::
1624  *
1625  * 2 vars: [min, max]
1626  *
1627  * ALLOCATION_LG2::
1628  *
1629  * 2 vars: [lg2min, lg2max]
1630  * 3 vars: [lg2min, lg2max, linear_offset]
1631  */
1632  int getAllocationNumVars() const;
1633  void getAllocationVars(float * vars) const;
1634  void setAllocationVars(int numvars, const float * vars);
1635 
1636  /**
1637  * *Transform*
1638  *
1639  * If a transform in the specified direction has been specified,
1640  * return it. Otherwise return a null ConstTransformRcPtr
1641  */
1642  ConstTransformRcPtr getTransform(ColorSpaceDirection dir) const noexcept;
1643  /**
1644  * Specify the transform for the appropriate direction.
1645  * Setting the transform to null will clear it.
1646  */
1647  void setTransform(const ConstTransformRcPtr & transform, ColorSpaceDirection dir);
1648 
1649  ColorSpace(const ColorSpace &) = delete;
1650  ColorSpace& operator= (const ColorSpace &) = delete;
1651  /// Do not use (needed only for pybind11).
1652  ~ColorSpace();
1653 
1654 private:
1655  explicit ColorSpace(ReferenceSpaceType referenceSpace);
1656  ColorSpace();
1657 
1658  static void deleter(ColorSpace* c);
1659 
1660  class Impl;
1661  Impl * m_impl;
1662  Impl * getImpl() { return m_impl; }
1663  const Impl * getImpl() const { return m_impl; }
1664 };
1665 
1666 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const ColorSpace&);
1667 
1668 
1669 
1670 
1671 //
1672 // ColorSpaceSet
1673 //
1674 
1675 
1676 /**
1677  * The *ColorSpaceSet* is a set of color spaces (i.e. no color space duplication)
1678  * which could be the result of \ref Config::getColorSpaces
1679  * or built from scratch.
1680  *
1681  * \note
1682  * The color spaces are decoupled from the config ones, i.e., any
1683  * changes to the set itself or to its color spaces do not affect the
1684  * original color spaces from the configuration. If needed,
1685  * use \ref Config::addColorSpace to update the configuration.
1686  */
1688 {
1689 public:
1690  /// Create an empty set of color spaces.
1691  static ColorSpaceSetRcPtr Create();
1692 
1693  /// Create a set containing a copy of all the color spaces.
1694  ColorSpaceSetRcPtr createEditableCopy() const;
1695 
1696  /**
1697  * \brief Return true if the two sets are equal.
1698  *
1699  * \note
1700  * The comparison is done on the color space names (not a deep comparison).
1701  */
1702  bool operator==(const ColorSpaceSet & css) const;
1703  /// Return true if the two sets are different.
1704  bool operator!=(const ColorSpaceSet & css) const;
1705 
1706  /// Return the number of color spaces.
1707  int getNumColorSpaces() const;
1708  /**
1709  * Return the color space name using its index.
1710  * This will be null if an invalid index is specified.
1711  */
1712  const char * getColorSpaceNameByIndex(int index) const;
1713  /**
1714  * Return the color space using its index.
1715  * This will be empty if an invalid index is specified.
1716  */
1717  ConstColorSpaceRcPtr getColorSpaceByIndex(int index) const;
1718 
1719  /**
1720  * \brief
1721  *
1722  * \note
1723  * Only accepts color space names (i.e. no role name).
1724  *
1725  * Will return null if the name is not found.
1726  */
1727  ConstColorSpaceRcPtr getColorSpace(const char * name) const;
1728  /**
1729  * Will return -1 if the name is not found.
1730  *
1731  * \note
1732  * Only accepts color space names (i.e. no role name).
1733  */
1734  int getColorSpaceIndex(const char * name) const;
1735  /**
1736  * \brief
1737  *
1738  * \note
1739  * Only accepts color space names (i.e. no role name)
1740  *
1741  * \param name
1742  * \return true
1743  * \return false
1744  */
1745  bool hasColorSpace(const char * name) const;
1746 
1747  /**
1748  * \brief Add color space(s).
1749  *
1750  * \note
1751  * If another color space is already registered with the same name,
1752  * this will overwrite it. This stores a copy of the specified
1753  * color space(s). Throws if one of the aliases is already assigned as
1754  * a name or alias to an existing color space.
1755  */
1756  void addColorSpace(const ConstColorSpaceRcPtr & cs);
1757  void addColorSpaces(const ConstColorSpaceSetRcPtr & cs);
1758 
1759  /**
1760  * \brief Remove color space(s) using color space names (i.e. no role name).
1761  *
1762  * \note
1763  * The removal of a missing color space does nothing.
1764  */
1765  void removeColorSpace(const char * name);
1766  void removeColorSpaces(const ConstColorSpaceSetRcPtr & cs);
1767 
1768  /// Clear all color spaces.
1769  void clearColorSpaces();
1770 
1771  /// Do not use (needed only for pybind11).
1772  ~ColorSpaceSet();
1773 
1774 private:
1775  ColorSpaceSet();
1776 
1777  ColorSpaceSet(const ColorSpaceSet &);
1778  ColorSpaceSet & operator= (const ColorSpaceSet &);
1779 
1780  static void deleter(ColorSpaceSet * c);
1781 
1782  class Impl;
1783  Impl * m_impl;
1784  Impl * getImpl() { return m_impl; }
1785  const Impl * getImpl() const { return m_impl; }
1786 };
1787 
1788 /** \defgroup ColorSpaceSetOperators
1789  * @{
1790  */
1791 
1792 /**
1793  * \brief Perform the union of two sets.
1794  *
1795  * \note
1796  * This function provides operations on two color space sets
1797  * where the result contains copied color spaces and no duplicates.
1798  *
1799  * \param lcss
1800  * \param rcss
1801  */
1803  const ConstColorSpaceSetRcPtr & rcss);
1804  /**
1805  * \brief Perform the intersection of two sets.
1806  *
1807  * \note
1808  * This function provides operations on two color space sets
1809  * where the result contains copied color spaces and no duplicates.
1810  *
1811  * \param lcss
1812  * \param rcss
1813  */
1815  const ConstColorSpaceSetRcPtr & rcss);
1816 /**
1817  * \brief Perform the difference of two sets.
1818  *
1819  * \note
1820  * This function provides operations on two color space sets
1821  * where the result contains copied color spaces and no duplicates.
1822  *
1823  * \param lcss
1824  * \param rcss
1825  */
1827  const ConstColorSpaceSetRcPtr & rcss);
1828 
1829 /** @}*/
1830 
1831 
1832 //
1833 // Look
1834 //
1835 
1836 /**
1837  * The *Look* is an 'artistic' image modification, in a specified image
1838  * state.
1839  * The processSpace defines the ColorSpace the image is required to be
1840  * in, for the math to apply correctly.
1841  */
1843 {
1844 public:
1845  static LookRcPtr Create();
1846 
1847  LookRcPtr createEditableCopy() const;
1848 
1849  const char * getName() const;
1850  void setName(const char * name);
1851 
1852  const char * getProcessSpace() const;
1853  void setProcessSpace(const char * processSpace);
1854 
1855  ConstTransformRcPtr getTransform() const;
1856  /// Setting a transform to a non-null call makes it allowed.
1857  void setTransform(const ConstTransformRcPtr & transform);
1858 
1859  ConstTransformRcPtr getInverseTransform() const;
1860  /// Setting a transform to a non-null call makes it allowed.
1861  void setInverseTransform(const ConstTransformRcPtr & transform);
1862 
1863  const char * getDescription() const;
1864  void setDescription(const char * description);
1865 
1866  Look(const Look &) = delete;
1867  Look& operator= (const Look &) = delete;
1868  /// Do not use (needed only for pybind11).
1869  ~Look();
1870 
1871 private:
1872  Look();
1873 
1874  static void deleter(Look* c);
1875 
1876  class Impl;
1877  Impl * m_impl;
1878  Impl * getImpl() { return m_impl; }
1879  const Impl * getImpl() const { return m_impl; }
1880 };
1881 
1882 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Look&);
1883 
1884 
1885 /**
1886  * \brief NamedTransform.
1887  *
1888  * A NamedTransform provides a way for config authors to include a set of color
1889  * transforms that are independent of the color space being processed. For example a "utility
1890  * curve" transform where there is no need to convert to or from a reference space.
1891  */
1892 
1894 {
1895 public:
1896  static NamedTransformRcPtr Create();
1897 
1898  virtual NamedTransformRcPtr createEditableCopy() const = 0;
1899 
1900  virtual const char * getName() const noexcept = 0;
1901  virtual void setName(const char * name) noexcept = 0;
1902 
1903  /// Aliases can be used instead of the name. They must be unique within the config.
1904  virtual size_t getNumAliases() const noexcept = 0;
1905  /// Return empty string if idx is out of range.
1906  virtual const char * getAlias(size_t idx) const noexcept = 0;
1907  /**
1908  * Nothing is done if alias is NULL or empty, if it is already there, or if it is already
1909  * the named transform name.
1910  */
1911  virtual void addAlias(const char * alias) noexcept = 0;
1912  /// Does nothing if alias is not present.
1913  virtual void removeAlias(const char * alias) noexcept = 0;
1914  virtual void clearAliases() noexcept = 0;
1915 
1916  /// \see ColorSpace::getFamily
1917  virtual const char * getFamily() const noexcept = 0;
1918  /// \see ColorSpace::setFamily
1919  virtual void setFamily(const char * family) noexcept = 0;
1920 
1921  virtual const char * getDescription() const noexcept = 0;
1922  virtual void setDescription(const char * description) noexcept = 0;
1923 
1924  /// \see ColorSpace::hasCategory
1925  virtual bool hasCategory(const char * category) const noexcept = 0;
1926  /// \see ColorSpace::addCategory
1927  virtual void addCategory(const char * category) noexcept = 0;
1928  /// \see ColorSpace::removeCategory
1929  virtual void removeCategory(const char * category) noexcept = 0;
1930  /// \see ColorSpace::getNumCategories
1931  virtual int getNumCategories() const noexcept = 0;
1932  /// \see ColorSpace::getCategory
1933  virtual const char * getCategory(int index) const noexcept = 0;
1934  /// \see ColorSpace::clearCategories
1935  virtual void clearCategories() noexcept = 0;
1936 
1937  /**
1938  * A NamedTransform is not a color space and does not have an encoding in the same sense.
1939  * However, it may be useful to associate a color space encoding that the transform is intended
1940  * to be used with, for organizational purposes.
1941  */
1942  virtual const char * getEncoding() const noexcept = 0;
1943  virtual void setEncoding(const char * encoding) noexcept = 0;
1944 
1945  virtual ConstTransformRcPtr getTransform(TransformDirection dir) const = 0;
1946  virtual void setTransform(const ConstTransformRcPtr & transform, TransformDirection dir) = 0;
1947 
1948  NamedTransform(const NamedTransform &) = delete;
1949  NamedTransform & operator= (const NamedTransform &) = delete;
1950  // Do not use (needed only for pybind11).
1951  virtual ~NamedTransform() = default;
1952 
1953 protected:
1954  NamedTransform() = default;
1955 };
1956 
1957 extern OCIOEXPORT std::ostream & operator<< (std::ostream &, const NamedTransform &);
1958 
1959 
1960 /**
1961  * A *ViewTransform* provides a conversion from the main (usually scene-referred) reference space
1962  * to the display-referred reference space. This allows splitting the conversion from the main
1963  * reference space to a display into two parts: the ViewTransform plus a display color space.
1964  *
1965  * It is also possible to provide a ViewTransform that converts from the display-referred
1966  * reference space back to that space. This is useful in cases when a ViewTransform is needed
1967  * when converting between displays (such as HDR to SDR).
1968  *
1969  * The ReferenceSpaceType indicates whether the ViewTransform converts from scene-to-display
1970  * reference or display-to-display reference.
1971  *
1972  * The from_reference transform direction is the one that is used when going out towards a display.
1973  */
1975 {
1976 public:
1977  static ViewTransformRcPtr Create(ReferenceSpaceType referenceSpace);
1978 
1979  ViewTransformRcPtr createEditableCopy() const;
1980 
1981  const char * getName() const noexcept;
1982  void setName(const char * name) noexcept;
1983 
1984  /// \see ColorSpace::getFamily
1985  const char * getFamily() const noexcept;
1986  /// \see ColorSpace::setFamily
1987  void setFamily(const char * family);
1988 
1989  const char * getDescription() const noexcept;
1990  void setDescription(const char * description);
1991 
1992  /// \see ColorSpace::hasCategory
1993  bool hasCategory(const char * category) const;
1994  /// \see ColorSpace::addCategory
1995  void addCategory(const char * category);
1996  /// \see ColorSpace::removeCategory
1997  void removeCategory(const char * category);
1998  /// \see ColorSpace::getNumCategories
1999  int getNumCategories() const;
2000  /// \see ColorSpace::getCategory
2001  const char * getCategory(int index) const;
2002  /// \see ColorSpace::clearCategories
2003  void clearCategories();
2004 
2005  ReferenceSpaceType getReferenceSpaceType() const noexcept;
2006 
2007  /**
2008  * If a transform in the specified direction has been specified, return it.
2009  * Otherwise return a null ConstTransformRcPtr
2010  */
2011  ConstTransformRcPtr getTransform(ViewTransformDirection dir) const noexcept;
2012 
2013  /**
2014  * Specify the transform for the appropriate direction. Setting the transform
2015  * to null will clear it.
2016  */
2017  void setTransform(const ConstTransformRcPtr & transform, ViewTransformDirection dir);
2018 
2019  ViewTransform(const ViewTransform &) = delete;
2020  ViewTransform & operator= (const ViewTransform &) = delete;
2021  /// Do not use (needed only for pybind11).
2022  ~ViewTransform();
2023 
2024 private:
2025  ViewTransform();
2026  explicit ViewTransform(ReferenceSpaceType referenceSpace);
2027 
2028  static void deleter(ViewTransform * c);
2029 
2030  class Impl;
2031  Impl * m_impl;
2032  Impl * getImpl() { return m_impl; }
2033  const Impl * getImpl() const { return m_impl; }
2034 };
2035 
2036 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const ViewTransform&);
2037 
2038 //
2039 // Processor
2040 //
2041 
2042 
2043 /**
2044  * The *Processor* represents a specific color transformation which is
2045  * the result of \ref Config::getProcessor.
2046  */
2048 {
2049 public:
2050  bool isNoOp() const;
2051 
2052  /**
2053  * True if the image transformation is non-separable.
2054  * For example, if a change in red may also cause a change in green or blue.
2055  */
2056  bool hasChannelCrosstalk() const;
2057 
2058  const char * getCacheID() const;
2059 
2060  /**
2061  * The ProcessorMetadata contains technical information
2062  * such as the number of files and looks used in the processor.
2063  */
2064  ConstProcessorMetadataRcPtr getProcessorMetadata() const;
2065 
2066  /**
2067  * Get a FormatMetadata containing the top level metadata
2068  * for the processor. For a processor from a CLF file, this corresponds to
2069  * the ProcessList metadata.
2070  */
2071  const FormatMetadata & getFormatMetadata() const;
2072 
2073  /**
2074  * Get the number of transforms that comprise the processor.
2075  * Each transform has a (potentially empty) FormatMetadata.
2076  */
2077  int getNumTransforms() const;
2078  /**
2079  * Get a FormatMetadata containing the metadata for a
2080  * transform within the processor. For a processor from a CLF file, this
2081  * corresponds to the metadata associated with an individual process node.
2082  */
2083  const FormatMetadata & getTransformFormatMetadata(int index) const;
2084 
2085  /**
2086  * Return a \ref GroupTransform that contains a copy of the transforms that comprise the
2087  * processor. (Changes to it will not modify the original processor.) Note that the
2088  * GroupTransform::write method may be used to serialize a Processor. Serializing to
2089  * CTF format is a useful technique for debugging Processor contents.
2090  */
2091  GroupTransformRcPtr createGroupTransform() const;
2092 
2093  /**
2094  * The returned pointer may be used to set the default value of any dynamic
2095  * properties of the requested type. Throws if the requested property is not found. Note
2096  * that if the processor contains several ops that support the requested property, only one
2097  * can be dynamic and only this one will be controlled.
2098  *
2099  * \note The dynamic properties are a convenient way to change on-the-fly values without
2100  * generating again and again a CPU or GPU processor instance. Color transformations can
2101  * contain dynamic properties from a ExposureContrastTransform for example.
2102  * So, Processor, CPUProcessor and GpuShaderCreator all have ways to manage dynamic
2103  * properties. However, the transform dynamic properties are decoupled between the types
2104  * of processor instances so that the same Processor can generate several independent CPU
2105  * and/or GPU processor instances i.e. changing the value of the exposure dynamic property
2106  * from a CPU processor instance does not affect the corresponding GPU processor instance.
2107  * Processor creation will log a warning if there are more than one property of a given type.
2108  * There may be more than one property of a given type, but only one will respond to parameter
2109  * updates, the others will use their original parameter values.
2110  */
2111  DynamicPropertyRcPtr getDynamicProperty(DynamicPropertyType type) const;
2112  /// True if at least one dynamic property of that type exists.
2113  bool hasDynamicProperty(DynamicPropertyType type) const noexcept;
2114  /// True if at least one dynamic property of any type exists and is dynamic.
2115  bool isDynamic() const noexcept;
2116 
2117  /**
2118  * Run the optimizer on a Processor to create a new Processor.
2119  * It is usually not necessary to call this since getting a CPUProcessor or GPUProcessor
2120  * will also optimize. However if you need both, calling this method first makes getting
2121  * a CPU and GPU Processor faster since the optimization is effectively only done once.
2122  */
2123  ConstProcessorRcPtr getOptimizedProcessor(OptimizationFlags oFlags) const;
2124 
2125  /**
2126  * Create a Processor that is optimized for a specific in and out bit-depth (as CPUProcessor
2127  * would do). This method is provided primarily for diagnostic purposes.
2128  */
2129  ConstProcessorRcPtr getOptimizedProcessor(BitDepth inBD, BitDepth outBD,
2130  OptimizationFlags oFlags) const;
2131 
2132  //
2133  // GPU Renderer
2134  //
2135 
2136  /// Get an optimized GPUProcessor instance.
2137  ConstGPUProcessorRcPtr getDefaultGPUProcessor() const;
2138  ConstGPUProcessorRcPtr getOptimizedGPUProcessor(OptimizationFlags oFlags) const;
2139 
2140  /**
2141  * Get an optimized GPUProcessor instance that will emulate the OCIO v1 GPU path. This approach
2142  * bakes some of the ops into a single Lut3D and so is less accurate than the current GPU
2143  * processing methods.
2144  */
2145  ConstGPUProcessorRcPtr getOptimizedLegacyGPUProcessor(OptimizationFlags oFlags,
2146  unsigned edgelen) const;
2147 
2148  //
2149  // CPU Renderer
2150  //
2151 
2152  /**
2153  * Get an optimized CPUProcessor instance.
2154  *
2155  * \note
2156  * This may provide higher fidelity than anticipated due to internal
2157  * optimizations. For example, if the inputColorSpace and the
2158  * outputColorSpace are members of the same family, no conversion
2159  * will be applied, even though strictly speaking quantization
2160  * should be added.
2161  *
2162  * \note
2163  * The typical use case to apply color processing to an image is:
2164  *
2165  * \code{.cpp}
2166  *
2167  * OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig();
2168  *
2169  * OCIO::ConstProcessorRcPtr processor
2170  * = config->getProcessor(colorSpace1, colorSpace2);
2171  *
2172  * OCIO::ConstCPUProcessorRcPtr cpuProcessor
2173  * = processor->getDefaultCPUProcessor();
2174  *
2175  * OCIO::PackedImageDesc img(imgDataPtr, imgWidth, imgHeight, imgChannels);
2176  * cpuProcessor->apply(img);
2177  *
2178  * \endcode
2179  */
2180  ConstCPUProcessorRcPtr getDefaultCPUProcessor() const;
2181  ConstCPUProcessorRcPtr getOptimizedCPUProcessor(OptimizationFlags oFlags) const;
2182  ConstCPUProcessorRcPtr getOptimizedCPUProcessor(BitDepth inBitDepth,
2183  BitDepth outBitDepth,
2184  OptimizationFlags oFlags) const;
2185 
2186  Processor(const Processor &) = delete;
2187  Processor & operator= (const Processor &) = delete;
2188  /// Do not use (needed only for pybind11).
2189  ~Processor();
2190 
2191 private:
2192  Processor();
2193 
2194  static ProcessorRcPtr Create();
2195 
2196  static void deleter(Processor* c);
2197 
2198  friend class Config;
2199 
2200  class Impl;
2201  Impl * m_impl;
2202  Impl * getImpl() { return m_impl; }
2203  const Impl * getImpl() const { return m_impl; }
2204 };
2205 
2206 
2207 ///////////////////////////////////////////////////////////////////////////
2208 // CPUProcessor
2209 
2211 {
2212 public:
2213  /// The in and out bit-depths must be equal for isNoOp to be true.
2214  bool isNoOp() const;
2215 
2216  /**
2217  * Equivalent to isNoOp from the underlying Processor, i.e., it ignores
2218  * in/out bit-depth differences.
2219  */
2220  bool isIdentity() const;
2221 
2222  bool hasChannelCrosstalk() const;
2223 
2224  const char * getCacheID() const;
2225 
2226  /// Bit-depth of the input pixel buffer.
2227  BitDepth getInputBitDepth() const;
2228  /// Bit-depth of the output pixel buffer.
2229  BitDepth getOutputBitDepth() const;
2230 
2231  /**
2232  * The returned pointer may be used to set the value of any dynamic properties
2233  * of the requested type. Throws if the requested property is not found. Note that if the
2234  * processor contains several ops that support the requested property, only one can be dynamic.
2235  *
2236  * \note The dynamic properties in this object are decoupled from the ones in the
2237  * \ref Processor it was generated from. For each dynamic property in the Processor,
2238  * there is one in the CPU processor.
2239  */
2240  DynamicPropertyRcPtr getDynamicProperty(DynamicPropertyType type) const;
2241 
2242  /**
2243  * \brief Apply to an image with any kind of channel ordering while
2244  * respecting the input and output bit-depths.
2245  */
2246  void apply(ImageDesc & imgDesc) const;
2247  void apply(const ImageDesc & srcImgDesc, ImageDesc & dstImgDesc) const;
2248 
2249  /**
2250  * Apply to a single pixel respecting that the input and output bit-depths
2251  * be 32-bit float and the image buffer be packed RGB/RGBA.
2252  *
2253  * \note
2254  * This is not as efficient as applying to an entire image at once.
2255  * If you are processing multiple pixels, and have the flexibility,
2256  * use the above function instead.
2257  */
2258  void applyRGB(float * pixel) const;
2259  void applyRGBA(float * pixel) const;
2260 
2261  CPUProcessor(const CPUProcessor &) = delete;
2262  CPUProcessor& operator= (const CPUProcessor &) = delete;
2263  /// Do not use (needed only for pybind11).
2264  ~CPUProcessor();
2265 
2266 private:
2267  CPUProcessor();
2268 
2269  static void deleter(CPUProcessor * c);
2270 
2271  friend class Processor;
2272 
2273  class Impl;
2274  Impl * m_impl;
2275  Impl * getImpl() { return m_impl; }
2276  const Impl * getImpl() const { return m_impl; }
2277 };
2278 
2279 
2280 ///////////////////////////////////////////////////////////////////////////
2281 // GPUProcessor
2282 
2284 {
2285 public:
2286  bool isNoOp() const;
2287 
2288  bool hasChannelCrosstalk() const;
2289 
2290  const char * getCacheID() const;
2291 
2292  /// Extract & Store the shader information to implement the color processing.
2293  void extractGpuShaderInfo(GpuShaderDescRcPtr & shaderDesc) const;
2294 
2295  /// Extract the shader information using a custom GpuShaderCreator class.
2296  void extractGpuShaderInfo(GpuShaderCreatorRcPtr & shaderCreator) const;
2297 
2298  GPUProcessor(const GPUProcessor &) = delete;
2299  GPUProcessor& operator= (const GPUProcessor &) = delete;
2300  /// Do not use (needed only for pybind11).
2301  ~GPUProcessor();
2302 
2303 private:
2304  GPUProcessor();
2305 
2306  static void deleter(GPUProcessor * c);
2307 
2308  friend class Processor;
2309 
2310  class Impl;
2311  Impl * m_impl;
2312  Impl * getImpl() { return m_impl; }
2313  const Impl * getImpl() const { return m_impl; }
2314 };
2315 
2316 
2317 /**
2318  * \brief
2319  *
2320  * This class contains meta information about the process that generated
2321  * this processor. The results of these functions do not
2322  * impact the pixel processing.
2323  */
2325 {
2326 public:
2327  static ProcessorMetadataRcPtr Create();
2328 
2329  int getNumFiles() const;
2330  const char * getFile(int index) const;
2331 
2332  int getNumLooks() const;
2333  const char * getLook(int index) const;
2334 
2335  void addFile(const char * fname);
2336  void addLook(const char * look);
2337 
2338  ProcessorMetadata(const ProcessorMetadata &) = delete;
2339  ProcessorMetadata& operator= (const ProcessorMetadata &) = delete;
2340  /// Do not use (needed only for pybind11).
2341  ~ProcessorMetadata();
2342 
2343 private:
2345 
2346  static void deleter(ProcessorMetadata* c);
2347 
2348  class Impl;
2349  Impl * m_impl;
2350  Impl * getImpl() { return m_impl; }
2351  const Impl * getImpl() const { return m_impl; }
2352 };
2353 
2354 
2355 
2356 /**
2357  * In certain situations it is necessary to serialize transforms into a variety
2358  * of application specific LUT formats. Note that not all file formats that may
2359  * be read also support baking.
2360  *
2361  * **Usage Example:** *Bake a CSP sRGB viewer LUT*
2362  *
2363  * \code{.cpp}
2364  *
2365  * OCIO::ConstConfigRcPtr config = OCIO::Config::CreateFromEnv();
2366  * OCIO::BakerRcPtr baker = OCIO::Baker::Create();
2367  * baker->setConfig(config);
2368  * baker->setFormat("csp");
2369  * baker->setInputSpace("lnf");
2370  * baker->setShaperSpace("log");
2371  * baker->setTargetSpace("sRGB");
2372  * auto & metadata = baker->getFormatMetadata();
2373  * metadata.addChildElement(OCIO::METADATA_DESCRIPTION, "A first comment");
2374  * metadata.addChildElement(OCIO::METADATA_DESCRIPTION, "A second comment");
2375  * std::ostringstream out;
2376  * baker->bake(out); // fresh bread anyone!
2377  * std::cout << out.str();
2378  *
2379  * \endcode
2380  */
2382 {
2383 public:
2384  /// Create a new Baker.
2385  static BakerRcPtr Create();
2386 
2387  /// Create a copy of this Baker.
2388  BakerRcPtr createEditableCopy() const;
2389 
2390  ConstConfigRcPtr getConfig() const;
2391  /// Set the config to use.
2392  void setConfig(const ConstConfigRcPtr & config);
2393 
2394  const char * getFormat() const;
2395  /// Set the LUT output format.
2396  void setFormat(const char * formatName);
2397 
2398  const FormatMetadata & getFormatMetadata() const;
2399  /**
2400  * Get editable *optional* format metadata. The metadata that will be used
2401  * varies based on the capability of the given file format. Formats such as CSP,
2402  * IridasCube, and ResolveCube will create comments in the file header using the value of
2403  * any first-level children elements of the formatMetadata. The CLF/CTF formats will make
2404  * use of the top-level "id" and "name" attributes and children elements "Description",
2405  * "InputDescriptor", "OutputDescriptor", and "Info".
2406  */
2407  FormatMetadata & getFormatMetadata();
2408 
2409  const char * getInputSpace() const;
2410  /// Set the input ColorSpace that the LUT will be applied to.
2411  void setInputSpace(const char * inputSpace);
2412 
2413  const char * getShaperSpace() const;
2414  /**
2415  * Set an *optional* ColorSpace to be used to shape / transfer the input
2416  * colorspace. This is mostly used to allocate an HDR luminance range into an LDR one.
2417  * If a shaper space is not explicitly specified, and the file format supports one, the
2418  * ColorSpace Allocation will be used (not implemented for all formats).
2419  */
2420  void setShaperSpace(const char * shaperSpace);
2421 
2422  const char * getLooks() const;
2423  /**
2424  * Set the looks to be applied during baking. Looks is a potentially comma
2425  * (or colon) delimited list of lookNames, where +/- prefixes are optionally allowed to
2426  * denote forward/inverse look specification. (And forward is assumed in the absence of
2427  * either).
2428  */
2429  void setLooks(const char * looks);
2430 
2431  const char * getTargetSpace() const;
2432  /// Set the target device colorspace for the LUT.
2433  void setTargetSpace(const char * targetSpace);
2434 
2435  int getShaperSize() const;
2436  /**
2437  * Override the default shaper LUT size. Default value is -1, which allows
2438  * each format to use its own most appropriate size. For the CLF format, the default uses
2439  * a half-domain LUT1D (which is ideal for scene-linear inputs).
2440  */
2441  void setShaperSize(int shapersize);
2442 
2443  int getCubeSize() const;
2444  /**
2445  * Override the default cube sample size.
2446  * default: <format specific>
2447  */
2448  void setCubeSize(int cubesize);
2449 
2450  /// Bake the LUT into the output stream.
2451  void bake(std::ostream & os) const;
2452 
2453  /// Get the number of LUT bakers.
2454  static int getNumFormats();
2455 
2456  /**
2457  * Get the LUT baker format name at index, return empty string if an invalid
2458  * index is specified.
2459  */
2460  static const char * getFormatNameByIndex(int index);
2461  /**
2462  * Get the LUT baker format extension at index, return empty string if an
2463  * invalid index is specified.
2464  */
2465  static const char * getFormatExtensionByIndex(int index);
2466 
2467  Baker(const Baker &) = delete;
2468  Baker& operator= (const Baker &) = delete;
2469  /// Do not use (needed only for pybind11).
2470  ~Baker();
2471 
2472 private:
2473  Baker();
2474 
2475  static void deleter(Baker* o);
2476 
2477  class Impl;
2478  Impl * m_impl;
2479  Impl * getImpl() { return m_impl; }
2480  const Impl * getImpl() const { return m_impl; }
2481 };
2482 
2483 
2484 ///////////////////////////////////////////////////////////////////////////
2485 // ImageDesc
2486 
2488 
2489 /**
2490  * \brief
2491  * This is a light-weight wrapper around an image, that provides a context
2492  * for pixel access. This does NOT claim ownership of the pixels or copy
2493  * image data.
2494  */
2496 {
2497 public:
2498  ImageDesc();
2499  virtual ~ImageDesc();
2500 
2501  /// Get a pointer to the red channel of the first pixel.
2502  virtual void * getRData() const = 0;
2503  /// Get a pointer to the green channel of the first pixel.
2504  virtual void * getGData() const = 0;
2505  /// Get a pointer to the blue channel of the first pixel.
2506  virtual void * getBData() const = 0;
2507  /**
2508  * Get a pointer to the alpha channel of the first pixel
2509  * or null as alpha channel is optional.
2510  */
2511  virtual void * getAData() const = 0;
2512 
2513  /// Get the bit-depth.
2514  virtual BitDepth getBitDepth() const = 0;
2515 
2516  /// Get the width to process (where x position starts at 0 and ends at width-1).
2517  virtual long getWidth() const = 0;
2518  /// Get the height to process (where y position starts at 0 and ends at height-1).
2519  virtual long getHeight() const = 0;
2520 
2521  /// Get the step in bytes to find the same color channel of the next pixel.
2522  virtual ptrdiff_t getXStrideBytes() const = 0;
2523  /**
2524  * Get the step in bytes to find the same color channel
2525  * of the pixel at the same position in the next line.
2526  */
2527  virtual ptrdiff_t getYStrideBytes() const = 0;
2528 
2529  /**
2530  * Is the image buffer in packed mode with the 4 color channels?
2531  * ("Packed" here means that XStrideBytes is 4x the bytes per channel, so it is more specific
2532  * than simply any PackedImageDesc.)
2533  */
2534  virtual bool isRGBAPacked() const = 0;
2535  /// Is the image buffer 32-bit float?
2536  virtual bool isFloat() const = 0;
2537 
2538 private:
2539  ImageDesc(const ImageDesc &);
2540  ImageDesc & operator= (const ImageDesc &);
2541 };
2542 
2543 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const ImageDesc&);
2544 
2545 
2546 ///////////////////////////////////////////////////////////////////////////
2547 // PackedImageDesc
2548 
2549 /**
2550  * All the constructors expect a pointer to packed image data (such as
2551  * rgbrgbrgb or rgbargbargba) starting at the first color channel of
2552  * the first pixel to process (which does not need to be the first pixel
2553  * of the image). The number of channels must be greater than or equal to 3.
2554  * If a 4th channel is specified, it is assumed to be alpha
2555  * information. Channels > 4 will be ignored.
2556  *
2557  * \note
2558  * The methods assume the CPUProcessor bit-depth type for the data pointer.
2559  */
2561 {
2562 public:
2563 
2564  /**
2565  * \note
2566  * numChannels must be 3 (RGB) or 4 (RGBA).
2567  */
2568  PackedImageDesc(void * data,
2569  long width, long height,
2570  long numChannels);
2571 
2572  /**
2573  * \note
2574  * numChannels must be 3 (RGB) or 4 (RGBA).
2575  */
2576  PackedImageDesc(void * data,
2577  long width, long height,
2578  long numChannels,
2579  BitDepth bitDepth,
2580  ptrdiff_t chanStrideBytes,
2581  ptrdiff_t xStrideBytes,
2582  ptrdiff_t yStrideBytes);
2583 
2584  PackedImageDesc(void * data,
2585  long width, long height,
2586  ChannelOrdering chanOrder);
2587 
2588  PackedImageDesc(void * data,
2589  long width, long height,
2590  ChannelOrdering chanOrder,
2591  BitDepth bitDepth,
2592  ptrdiff_t chanStrideBytes,
2593  ptrdiff_t xStrideBytes,
2594  ptrdiff_t yStrideBytes);
2595 
2596  virtual ~PackedImageDesc();
2597 
2598  /// Get the channel ordering of all the pixels.
2599  ChannelOrdering getChannelOrder() const;
2600 
2601  /// Get the bit-depth.
2602  BitDepth getBitDepth() const override;
2603 
2604  /// Get a pointer to the first color channel of the first pixel.
2605  void * getData() const;
2606 
2607  void * getRData() const override;
2608  void * getGData() const override;
2609  void * getBData() const override;
2610  void * getAData() const override;
2611 
2612  long getWidth() const override;
2613  long getHeight() const override;
2614  long getNumChannels() const;
2615 
2616  ptrdiff_t getChanStrideBytes() const;
2617  ptrdiff_t getXStrideBytes() const override;
2618  ptrdiff_t getYStrideBytes() const override;
2619 
2620  bool isRGBAPacked() const override;
2621  bool isFloat() const override;
2622 
2623 private:
2624  struct Impl;
2625  Impl * m_impl;
2626  Impl * getImpl() { return m_impl; }
2627  const Impl * getImpl() const { return m_impl; }
2628 
2629  PackedImageDesc();
2631  PackedImageDesc& operator= (const PackedImageDesc &);
2632 };
2633 
2634 
2635 ///////////////////////////////////////////////////////////////////////////
2636 // PlanarImageDesc
2637 
2638 /**
2639  * All the constructors expect pointers to the specified image planes
2640  * (i.e. rrrr gggg bbbb) starting at the first color channel of the
2641  * first pixel to process (which need not be the first pixel of the image).
2642  * Pass NULL for aData if no alpha exists (r/g/bData must not be NULL).
2643  *
2644  * \note
2645  * The methods assume the CPUProcessor bit-depth type for the R/G/B/A data pointers.
2646  */
2648 {
2649 public:
2650 
2651  PlanarImageDesc(void * rData, void * gData, void * bData, void * aData,
2652  long width, long height);
2653 
2654  /**
2655  *
2656  * Note that although PlanarImageDesc is powerful enough to also describe
2657  * all PackedImageDesc scenarios, it is recommended to use
2658  * a PackedImageDesc where possible since that allows for additional
2659  * optimizations.
2660  */
2661  PlanarImageDesc(void * rData, void * gData, void * bData, void * aData,
2662  long width, long height,
2663  BitDepth bitDepth,
2664  ptrdiff_t xStrideBytes,
2665  ptrdiff_t yStrideBytes);
2666 
2667  virtual ~PlanarImageDesc();
2668 
2669  void * getRData() const override;
2670  void * getGData() const override;
2671  void * getBData() const override;
2672  void * getAData() const override;
2673 
2674  /// Get the bit-depth.
2675  BitDepth getBitDepth() const override;
2676 
2677  long getWidth() const override;
2678  long getHeight() const override;
2679 
2680  ptrdiff_t getXStrideBytes() const override;
2681  ptrdiff_t getYStrideBytes() const override;
2682 
2683  bool isRGBAPacked() const override;
2684  bool isFloat() const override;
2685 
2686 private:
2687  struct Impl;
2688  Impl * m_impl;
2689  Impl * getImpl() { return m_impl; }
2690  const Impl * getImpl() const { return m_impl; }
2691 
2692  PlanarImageDesc();
2694  PlanarImageDesc& operator= (const PlanarImageDesc &);
2695 };
2696 
2697 
2698 ///////////////////////////////////////////////////////////////////////////
2699 // GpuShaderCreator
2700 /**
2701  * Inherit from the class to fully customize the implementation of a GPU shader program
2702  * from a color transformation.
2703  *
2704  * When no customizations are needed and the intermediate in-memory step is acceptable then the
2705  * \ref GpuShaderDesc is a better choice.
2706  *
2707  * \note
2708  * To better decouple the \ref DynamicProperties from their GPU implementation, the code provides
2709  * several addUniform() methods i.e. one per access function types. For example, an
2710  * \ref ExposureContrastTransform instance owns three \ref DynamicProperties and they are all
2711  * implemented by a double. When creating the GPU fragment shader program, the addUniform() with
2712  * GpuShaderCreator::DoubleGetter is called when property is dynamic, up to three times.
2713  *
2714  * **An OCIO shader program could contain:**
2715  *
2716  * * A declaration part e.g., uniform sampled3D tex3;
2717  *
2718  * * Some helper methods
2719  *
2720  * * The OCIO shader function may be broken down as:
2721  *
2722  * * The function header e.g., void OCIODisplay(in vec4 inColor) {
2723  * * The function body e.g., vec4 outColor.rgb = texture3D(tex3, inColor.rgb).rgb;
2724  * * The function footer e.g., return outColor; }
2725  *
2726  *
2727  * **Usage Example:**
2728  *
2729  * Below is a code snippet to highlight the different parts of the OCIO shader program.
2730  *
2731  * \code{.cpp}
2732  *
2733  * // All global declarations
2734  * uniform sampled3D tex3;
2735  *
2736  * // All helper methods
2737  * vec3 computePosition(vec3 color)
2738  * {
2739  * vec3 coords = color;
2740  * // Some processing...
2741  * return coords;
2742  * }
2743  *
2744  * // The shader function
2745  * vec4 OCIODisplay(in vec4 inColor) //
2746  * { // Function Header
2747  * vec4 outColor = inColor; //
2748  *
2749  * outColor.rgb = texture3D(tex3, computePosition(inColor.rgb)).rgb;
2750  *
2751  * return outColor; // Function Footer
2752  * } //
2753  *
2754  * \endcode
2755  */
2757 {
2758 public:
2759 
2760  virtual GpuShaderCreatorRcPtr clone() const = 0;
2761 
2762  const char * getUniqueID() const noexcept;
2763  void setUniqueID(const char * uid) noexcept;
2764 
2765  GpuLanguage getLanguage() const noexcept;
2766  /// Set the shader program language.
2767  void setLanguage(GpuLanguage lang) noexcept;
2768 
2769  const char * getFunctionName() const noexcept;
2770  // Set the function name of the shader program.
2771  void setFunctionName(const char * name) noexcept;
2772 
2773  const char * getPixelName() const noexcept;
2774  /// Set the pixel name variable holding the color values.
2775  void setPixelName(const char * name) noexcept;
2776 
2777  /**
2778  *
2779  * \note
2780  * Some applications require that textures, uniforms,
2781  * and helper methods be uniquely named because several
2782  * processor instances could coexist.
2783  */
2784  const char * getResourcePrefix() const noexcept;
2785  /// Set a prefix to the resource name
2786  void setResourcePrefix(const char * prefix) noexcept;
2787 
2788  virtual const char * getCacheID() const noexcept;
2789 
2790  /// Start to collect the shader data.
2791  virtual void begin(const char * uid);
2792  /// End to collect the shader data.
2793  virtual void end();
2794 
2795  /// Some graphic cards could have 1D & 2D textures with size limitations.
2796  virtual void setTextureMaxWidth(unsigned maxWidth) = 0;
2797  virtual unsigned getTextureMaxWidth() const noexcept = 0;
2798 
2799  /**
2800  * To avoid global texture sampler and uniform name clashes always append an increasing index
2801  * to the resource name.
2802  */
2803  unsigned getNextResourceIndex() noexcept;
2804 
2805  /// Function returning a double, used by uniforms. GPU converts double to float.
2806  typedef std::function<double()> DoubleGetter;
2807  /// Function returning a bool, used by uniforms.
2808  typedef std::function<bool()> BoolGetter;
2809  /// Functions returning a Float3, used by uniforms.
2810  typedef std::function<const Float3 &()> Float3Getter;
2811  /// Function returning an int, used by uniforms.
2812  typedef std::function<int()> SizeGetter;
2813  /// Function returning a float *, used by uniforms.
2814  typedef std::function<const float *()> VectorFloatGetter;
2815  /// Function returning an int *, used by uniforms.
2816  typedef std::function<const int *()> VectorIntGetter;
2817 
2818  virtual bool addUniform(const char * name,
2819  const DoubleGetter & getDouble) = 0;
2820 
2821  virtual bool addUniform(const char * name,
2822  const BoolGetter & getBool) = 0;
2823 
2824  virtual bool addUniform(const char * name,
2825  const Float3Getter & getFloat3) = 0;
2826 
2827  virtual bool addUniform(const char * name,
2828  const SizeGetter & getSize,
2829  const VectorFloatGetter & getVectorFloat) = 0;
2830 
2831  virtual bool addUniform(const char * name,
2832  const SizeGetter & getSize,
2833  const VectorIntGetter & getVectorInt) = 0;
2834 
2835  /// Adds the property (used internally).
2836  void addDynamicProperty(DynamicPropertyRcPtr & prop);
2837 
2838  /// Dynamic Property related methods.
2839  unsigned getNumDynamicProperties() const noexcept;
2840  DynamicPropertyRcPtr getDynamicProperty(unsigned index) const;
2841 
2842  bool hasDynamicProperty(DynamicPropertyType type) const;
2843  /**
2844  * Dynamic properties allow changes once the fragment shader program has been created. The
2845  * steps are to get the appropriate DynamicProperty instance, and then change its value.
2846  */
2847  DynamicPropertyRcPtr getDynamicProperty(DynamicPropertyType type) const;
2848 
2850  {
2851  TEXTURE_RED_CHANNEL, ///< Only need a red channel texture
2852  TEXTURE_RGB_CHANNEL ///< Need a RGB texture
2853  };
2854 
2855  /**
2856  * Add a 2D texture (1D texture if height equals 1).
2857  *
2858  * \note
2859  * The 'values' parameter contains the LUT data which must be used as-is as the dimensions and
2860  * origin are hard-coded in the fragment shader program. So, it means one GPU texture per entry.
2861  **/
2862  virtual void addTexture(const char * textureName,
2863  const char * samplerName,
2864  unsigned width, unsigned height,
2865  TextureType channel,
2866  Interpolation interpolation,
2867  const float * values) = 0;
2868 
2869  /**
2870  * Add a 3D texture with RGB channel type.
2871  *
2872  * \note
2873  * The 'values' parameter contains the 3D LUT data which must be used as-is as the dimension
2874  * and origin are hard-coded in the fragment shader program. So, it means one GPU 3D texture
2875  * per entry.
2876  **/
2877  virtual void add3DTexture(const char * textureName,
2878  const char * samplerName,
2879  unsigned edgelen,
2880  Interpolation interpolation,
2881  const float * values) = 0;
2882 
2883  // Methods to specialize parts of a OCIO shader program
2884  virtual void addToDeclareShaderCode(const char * shaderCode);
2885  virtual void addToHelperShaderCode(const char * shaderCode);
2886  virtual void addToFunctionHeaderShaderCode(const char * shaderCode);
2887  virtual void addToFunctionShaderCode(const char * shaderCode);
2888  virtual void addToFunctionFooterShaderCode(const char * shaderCode);
2889 
2890  /**
2891  * \brief Create the OCIO shader program
2892  *
2893  * \note
2894  * The OCIO shader program is decomposed to allow a specific implementation
2895  * to change some parts. Some product integrations add the color processing
2896  * within a client shader program, imposing constraints requiring this flexibility.
2897  */
2898  virtual void createShaderText(const char * shaderDeclarations,
2899  const char * shaderHelperMethods,
2900  const char * shaderFunctionHeader,
2901  const char * shaderFunctionBody,
2902  const char * shaderFunctionFooter);
2903 
2904  virtual void finalize();
2905 
2906  GpuShaderCreator(const GpuShaderCreator &) = delete;
2907  GpuShaderCreator & operator= (const GpuShaderCreator &) = delete;
2908  /// Do not use (needed only for pybind11).
2909  virtual ~GpuShaderCreator();
2910 
2911 protected:
2912  GpuShaderCreator();
2913 
2914  class Impl;
2915  Impl * m_impl;
2916  Impl * getImpl() { return m_impl; }
2917  const Impl * getImpl() const { return m_impl; }
2918 };
2919 
2920 // GpuShaderDesc
2921 /**
2922  * \brief This class holds the GPU-related information needed to build a shader program
2923  * from a specific processor.
2924  *
2925  * This class defines the interface and there are two implementations provided.
2926  * The "legacy" mode implements the OCIO v1 approach of baking certain ops
2927  * in order to have at most one 3D-LUT. The "generic" mode is the v2 default and
2928  * allows all the ops to be processed as-is, without baking, like the CPU renderer.
2929  * Custom implementations could be written to accommodate the GPU needs of a
2930  * specific client app.
2931  *
2932  *
2933  * The complete fragment shader program is decomposed in two main parts:
2934  * the OCIO shader program for the color processing and the client shader
2935  * program which consumes the pixel color processing.
2936  *
2937  * The OCIO shader program is fully described by the GpuShaderDesc
2938  * independently from the client shader program. The only critical
2939  * point is the agreement on the OCIO function shader name.
2940  *
2941  * To summarize, the complete shader program is:
2942  *
2943  * \code{.cpp}
2944  *
2945  * ////////////////////////////////////////////////////////////////////////
2946  * // //
2947  * // The complete fragment shader program //
2948  * // //
2949  * ////////////////////////////////////////////////////////////////////////
2950  * // //
2951  * // ////////////////////////////////////////////////////////////// //
2952  * // // // //
2953  * // // The OCIO shader program // //
2954  * // // // //
2955  * // ////////////////////////////////////////////////////////////// //
2956  * // // // //
2957  * // // // All global declarations // //
2958  * // // uniform sampled3D tex3; // //
2959  * // // // //
2960  * // // // All helper methods // //
2961  * // // vec3 computePos(vec3 color) // //
2962  * // // { // //
2963  * // // vec3 coords = color; // //
2964  * // // ... // //
2965  * // // return coords; // //
2966  * // // } // //
2967  * // // // //
2968  * // // // The OCIO shader function // //
2969  * // // vec4 OCIODisplay(in vec4 inColor) // //
2970  * // // { // //
2971  * // // vec4 outColor = inColor; // //
2972  * // // ... // //
2973  * // // outColor.rbg // //
2974  * // // = texture3D(tex3, computePos(inColor.rgb)).rgb; // //
2975  * // // ... // //
2976  * // // return outColor; // //
2977  * // // } // //
2978  * // // // //
2979  * // ////////////////////////////////////////////////////////////// //
2980  * // //
2981  * // ////////////////////////////////////////////////////////////// //
2982  * // // // //
2983  * // // The client shader program // //
2984  * // // // //
2985  * // ////////////////////////////////////////////////////////////// //
2986  * // // // //
2987  * // // uniform sampler2D image; // //
2988  * // // // //
2989  * // // void main() // //
2990  * // // { // //
2991  * // // vec4 inColor = texture2D(image, gl_TexCoord[0].st); // //
2992  * // // ... // //
2993  * // // vec4 outColor = OCIODisplay(inColor); // //
2994  * // // ... // //
2995  * // // gl_FragColor = outColor; // //
2996  * // // } // //
2997  * // // // //
2998  * // ////////////////////////////////////////////////////////////// //
2999  * // //
3000  * ////////////////////////////////////////////////////////////////////////
3001  * \endcode
3002  *
3003  * **Usage Example:** *Building a GPU shader*
3004  *
3005  * This example is based on the code in: src/apps/ociodisplay/main.cpp
3006  *
3007  * \code{.cpp}
3008  *
3009  * // Get the processor
3010  * //
3011  * OCIO::ConstConfigRcPtr config = OCIO::Config::CreateFromEnv();
3012  * OCIO::ConstProcessorRcPtr processor
3013  * = config->getProcessor("ACES - ACEScg", "Output - sRGB");
3014  *
3015  * // Step 1: Create a GPU shader description
3016  * //
3017  * // The two potential scenarios are:
3018  * //
3019  * // 1. Instantiate the generic shader description. The color processor
3020  * // is used as-is (i.e. without any baking step) and could contain
3021  * // any number of 1D & 3D luts.
3022  * //
3023  * // This is the default OCIO v2 behavior and allows a much better
3024  * // match between the CPU and GPU renderers.
3025  * //
3026  * OCIO::GpuShaderDescRcPtr shaderDesc = OCIO::GpuShaderDesc::Create();
3027  * //
3028  * // 2. Instantiate a custom shader description.
3029  * //
3030  * // Writing a custom shader description is a way to tailor the shaders
3031  * // to the needs of a given client program. This involves writing a
3032  * // new class inheriting from the pure virtual class GpuShaderDesc.
3033  * //
3034  * // Please refer to the GenericGpuShaderDesc class for an example.
3035  * //
3036  * OCIO::GpuShaderDescRcPtr shaderDesc = MyCustomGpuShader::Create();
3037  *
3038  * shaderDesc->setLanguage(OCIO::GPU_LANGUAGE_GLSL_1_2);
3039  * shaderDesc->setFunctionName("OCIODisplay");
3040  *
3041  * // Step 2: Collect the shader program information for a specific processor
3042  * //
3043  * processor->extractGpuShaderInfo(shaderDesc);
3044  *
3045  * // Step 3: Create a helper to build the shader. Here we use a helper for
3046  * // OpenGL but there will also be helpers for other languages.
3047  * //
3048  * OpenGLBuilderRcPtr oglBuilder = OpenGLBuilder::Create(shaderDesc);
3049  *
3050  * // Step 4: Allocate & upload all the LUTs
3051  * //
3052  * oglBuilder->allocateAllTextures();
3053  *
3054  * // Step 5: Build the complete fragment shader program using
3055  * // g_fragShaderText which is the client shader program.
3056  * //
3057  * g_programId = oglBuilder->buildProgram(g_fragShaderText);
3058  *
3059  * // Step 6: Enable the fragment shader program, and all needed textures
3060  * //
3061  * glUseProgram(g_programId);
3062  * glUniform1i(glGetUniformLocation(g_programId, "tex1"), 1); // image texture
3063  * oglBuilder->useAllTextures(g_programId); // LUT textures
3064  *
3065  * // Step 7: Update uniforms from dynamic property instances.
3066  * m_oglBuilder->useAllUniforms();
3067  * \endcode
3068  *
3069  */
3071 {
3072 public:
3073 
3074  /// Create the default shader description.
3075  static GpuShaderDescRcPtr CreateShaderDesc();
3076 
3077  GpuShaderCreatorRcPtr clone() const override;
3078 
3079  /**
3080  * Used to retrieve uniform information. UniformData m_type indicates the type of uniform
3081  * and what member of the structure should be used:
3082  * * UNIFORM_DOUBLE: m_getDouble.
3083  * * UNIFORM_BOOL: m_getBool.
3084  * * UNIFORM_FLOAT3: m_getFloat3.
3085  * * UNIFORM_VECTOR_FLOAT: m_vectorFloat.
3086  * * UNIFORM_VECTOR_INT: m_vectorInt.
3087  */
3089  {
3090  UniformData() = default;
3091  UniformData(const UniformData & data) = default;
3093  DoubleGetter m_getDouble{};
3094  BoolGetter m_getBool{};
3095  Float3Getter m_getFloat3{};
3097  {
3098  SizeGetter m_getSize{};
3099  VectorFloatGetter m_getVector{};
3100  } m_vectorFloat{};
3101  struct VectorInt
3102  {
3103  SizeGetter m_getSize{};
3104  VectorIntGetter m_getVector{};
3105  } m_vectorInt{};
3106  };
3107  virtual unsigned getNumUniforms() const noexcept = 0;
3108  /// Returns name of uniform and data as parameter.
3109  virtual const char * getUniform(unsigned index, UniformData & data) const = 0;
3110 
3111  // 1D lut related methods
3112  virtual unsigned getNumTextures() const noexcept = 0;
3113  virtual void getTexture(unsigned index,
3114  const char *& textureName,
3115  const char *& samplerName,
3116  unsigned & width,
3117  unsigned & height,
3118  TextureType & channel,
3119  Interpolation & interpolation) const = 0;
3120  virtual void getTextureValues(unsigned index, const float *& values) const = 0;
3121 
3122  // 3D lut related methods
3123  virtual unsigned getNum3DTextures() const noexcept = 0;
3124  virtual void get3DTexture(unsigned index,
3125  const char *& textureName,
3126  const char *& samplerName,
3127  unsigned & edgelen,
3128  Interpolation & interpolation) const = 0;
3129  virtual void get3DTextureValues(unsigned index, const float *& values) const = 0;
3130 
3131  /// Get the complete OCIO shader program.
3132  const char * getShaderText() const noexcept;
3133 
3134  GpuShaderDesc(const GpuShaderDesc &) = delete;
3135  GpuShaderDesc& operator= (const GpuShaderDesc &) = delete;
3136  /// Do not use (needed only for pybind11).
3137  virtual ~GpuShaderDesc();
3138 
3139 protected:
3140  GpuShaderDesc();
3141 };
3142 
3143 
3144 /**
3145  * Context
3146  *
3147  * A context defines some overrides to a Config. For example, it can override the
3148  * search path or change the value of a context variable.
3149  *
3150  * \note
3151  * Only some \ref Config::getProcessor methods accept a custom context; otherwise,
3152  * the default context instance is used (see \ref Config::getCurrentContext).
3153  *
3154  * Context Variables
3155  *
3156  * The context variables allow changes at runtime using environment variables. For example,
3157  * a color space name (such as src & dst for the ColorSpaceTransform) or a file
3158  * name (such as LUT file name for the FileTransform) could be defined by context
3159  * variables. The color transformation is then customized based on some environment variables.
3160  *
3161  * In a config the context variables support three syntaxes (i.e. ${VAR}, $VAR and %VAR%) and
3162  * the parsing starts from longest to shortest. So, the resolve works like '$TEST_$TESTING_$TE'
3163  * expands in this order '2 1 3'.
3164  *
3165  * Config authors are recommended to include the "environment" section in their configs. This
3166  * improves performance as well as making the config more readable. When present, this section
3167  * must declare all context variables used in the config. It may also provide a default value,
3168  * in case the variable is not present in the user's environment.
3169  *
3170  * A context variable may only be used in the following places:
3171  * * the \ref `ColorSpaceTransform` to define the source and the destination color space names,
3172  * * the \ref `FileTransform` to define the source file name (e.g. a LUT file name),
3173  * * the search_path,
3174  * * the cccid of the \ref `FileTransform` to only extract one specific transform from
3175  * the CDL & CCC files.
3176  *
3177  * Some specific restrictions are worth calling out:
3178  * * they cannot be used as either the name or value of a role,
3179  * * the context variable characters $ and % are prohibited in a color space name.
3180  */
3182 {
3183 public:
3184  static ContextRcPtr Create();
3185 
3186  ContextRcPtr createEditableCopy() const;
3187 
3188  const char * getCacheID() const;
3189 
3190  void setSearchPath(const char * path);
3191  const char * getSearchPath() const;
3192 
3193  int getNumSearchPaths() const;
3194  const char * getSearchPath(int index) const;
3195  void clearSearchPaths();
3196  void addSearchPath(const char * path);
3197  void setWorkingDir(const char * dirname);
3198  const char * getWorkingDir() const;
3199 
3200  /// Add (or update) a context variable. But it removes it if the value argument
3201  /// is null.
3202  void setStringVar(const char * name, const char * value) noexcept;
3203  /// Get the context variable value. It returns an empty string if the context
3204  /// variable is null or does not exist.
3205  const char * getStringVar(const char * name) const noexcept;
3206 
3207  int getNumStringVars() const;
3208  const char * getStringVarNameByIndex(int index) const;
3209 
3210  const char * getStringVarByIndex(int index) const;
3211 
3212  void clearStringVars();
3213 
3214  /// Add to the instance all the context variables from ctx.
3215  void addStringVars(const ConstContextRcPtr & ctx) noexcept;
3216 
3217 
3218  void setEnvironmentMode(EnvironmentMode mode) noexcept;
3219 
3220 
3221  EnvironmentMode getEnvironmentMode() const noexcept;
3222 
3223  /// Seed all string vars with the current environment.
3224  void loadEnvironment() noexcept;
3225 
3226  /// Resolve all the context variables from the string. It could be color space
3227  /// names or file names. Note that it recursively applies the context variable resolution.
3228  /// Returns the string unchanged if it does not contain any context variable.
3229  const char * resolveStringVar(const char * string) const noexcept;
3230  /// Resolve all the context variables from the string and return all the context
3231  /// variables used to resolve the string (empty if no context variables were used).
3232  const char * resolveStringVar(const char * string, ContextRcPtr & usedContextVars) const noexcept;
3233 
3234  /**
3235  * Build the resolved and expanded filepath using the search_path when needed,
3236  * and check if the filepath exists. If it cannot be resolved or found, an exception will be
3237  * thrown. The method argument is directly from the config file so it can be an absolute or
3238  * relative file path or a file name.
3239  *
3240  * \note The filepath existence check could add a performance hit.
3241  *
3242  * \note The context variable resolution is performed using :cpp:func:`resolveStringVar`.
3243  */
3244  const char * resolveFileLocation(const char * filename) const;
3245  /// Build the resolved and expanded filepath and return all the context variables
3246  /// used to resolve the filename (empty if no context variables were used).
3247  const char * resolveFileLocation(const char * filename, ContextRcPtr & usedContextVars) const;
3248 
3249  Context(const Context &) = delete;
3250  Context& operator= (const Context &) = delete;
3251  /// Do not use (needed only for pybind11).
3252  ~Context();
3253 
3254 private:
3255  Context();
3256 
3257  static void deleter(Context* c);
3258 
3259  class Impl;
3260  Impl * m_impl;
3261  Impl * getImpl() { return m_impl; }
3262  const Impl * getImpl() const { return m_impl; }
3263 };
3264 
3265 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Context&);
3266 
3267 
3268 ///////////////////////////////////////////////////////////////////////////
3269 // BuiltinTransformRegistry
3270 
3271 /**
3272  * The built-in transform registry contains all the existing built-in transforms which can
3273  * be used by a configuration (version 2 or higher only).
3274  */
3276 {
3277 public:
3279  BuiltinTransformRegistry & operator= (const BuiltinTransformRegistry &) = delete;
3280 
3281  /// Get the current built-in transform registry.
3282  static ConstBuiltinTransformRegistryRcPtr Get() noexcept;
3283 
3284  /// Get the number of built-in transforms available.
3285  virtual size_t getNumBuiltins() const noexcept = 0;
3286  /**
3287  * Get the style string for the i-th built-in transform.
3288  * The style is the ID string that identifies a given transform.
3289  */
3290  virtual const char * getBuiltinStyle(size_t index) const = 0;
3291  /// Get the description string for the i-th built-in transform.
3292  virtual const char * getBuiltinDescription(size_t index) const = 0;
3293 
3294 protected:
3295  BuiltinTransformRegistry() = default;
3296  virtual ~BuiltinTransformRegistry() = default;
3297 };
3298 
3299 
3300 ///////////////////////////////////////////////////////////////////////////
3301 // SystemMonitors
3302 
3303 /**
3304  * Provides access to the ICC monitor profile provided by the operating system for each active display.
3305  */
3307 {
3308 public:
3309  SystemMonitors(const SystemMonitors &) = delete;
3310  SystemMonitors & operator= (const SystemMonitors &) = delete;
3311 
3312  /// Get the existing instance.
3313  static ConstSystemMonitorsRcPtr Get() noexcept;
3314 
3315  /**
3316  * True if the OS is able to provide ICC profiles for the attached monitors (macOS, Windows)
3317  * and false otherwise.
3318  */
3319  virtual bool isSupported() const noexcept = 0;
3320 
3321  /**
3322  * \defgroup Methods to access some information of the attached and active monitors.
3323  * @{
3324  */
3325 
3326  /// Get the number of active monitors reported by the operating system.
3327  virtual size_t getNumMonitors() const noexcept = 0;
3328 
3329  /**
3330  * \brief Get the monitor profile name.
3331  *
3332  * Get the string describing the monitor. It is used as an argument to instantiateDisplay. It
3333  * may also be used in a UI to ask a user which of several monitors they want to instantiate a
3334  * display for.
3335  */
3336  virtual const char * getMonitorName(size_t idx) const = 0;
3337  /// Get the ICC profile path associated to the monitor.
3338  virtual const char * getProfileFilepath(size_t idx) const = 0;
3339 
3340  /** @} */
3341 
3342 protected:
3343  SystemMonitors() = default;
3344  virtual ~SystemMonitors() = default;
3345 };
3346 
3347 } // namespace OCIO_NAMESPACE
3348 
3349 #endif // INCLUDED_OCIO_OPENCOLORIO_H
OCIOEXPORT ConstColorSpaceSetRcPtr operator-(const ConstColorSpaceSetRcPtr &lcss, const ConstColorSpaceSetRcPtr &rcss)
Perform the difference of two sets.
OCIOEXPORT ConstConfigRcPtr GetCurrentConfig()
Get the current configuration.
GLuint GLsizei const GLchar * message
Definition: glcorearb.h:2543
OCIO_SHARED_PTR< const ViewTransform > ConstViewTransformRcPtr
static const char * DefaultRuleName
Reserved rule name for the default rule.
Definition: OpenColorIO.h:1208
class OCIOEXPORT GpuShaderDesc
GT_API const UT_StringHolder filename
This class holds the GPU-related information needed to build a shader program from a specific process...
Definition: OpenColorIO.h:3070
std::function< const float *()> VectorFloatGetter
Function returning a float *, used by uniforms.
Definition: OpenColorIO.h:2814
class OCIOEXPORT ColorSpaceSet
OCIOEXPORT void SetLoggingLevel(LoggingLevel level)
Set the global logging level.
OCIO_SHARED_PTR< ViewingRules > ViewingRulesRcPtr
OCIOEXPORT void SetComputeHashFunction(ComputeHashFunction hashFunction)
Set the Compute Hash Function to use; otherwise, use the default.
OCIO_SHARED_PTR< GpuShaderCreator > GpuShaderCreatorRcPtr
*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
ChannelOrdering
Used by PackedImageDesc to indicate the channel ordering of the image to process. ...
This is a light-weight wrapper around an image, that provides a context for pixel access...
Definition: OpenColorIO.h:2495
OCIO_SHARED_PTR< Processor > ProcessorRcPtr
IMF_EXPORT IMATH_NAMESPACE::V3f direction(const IMATH_NAMESPACE::Box2i &dataWindow, const IMATH_NAMESPACE::V2f &pixelPosition)
class OCIOEXPORT BuiltinTransformRegistry
const GLfloat * c
Definition: glew.h:16631
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
OptimizationFlags
Provides control over how the ops in a Processor are combined in order to improve performance...
const Impl * getImpl() const
Definition: OpenColorIO.h:2917
class OCIOEXPORT ViewingRules
OCIO_SHARED_PTR< const Transform > ConstTransformRcPtr
GLint level
Definition: glcorearb.h:108
bool isIdentity(const MatType &m)
Determine if a matrix is an identity matrix.
Definition: Mat.h:882
OCIO_SHARED_PTR< FileRules > FileRulesRcPtr
std::function< int()> SizeGetter
Function returning an int, used by uniforms.
Definition: OpenColorIO.h:2812
An exception class to throw for errors detected at runtime.
Definition: OpenColorIO.h:76
OCIO_SHARED_PTR< const BuiltinTransformRegistry > ConstBuiltinTransformRegistryRcPtr
std::function< const Float3 &()> Float3Getter
Functions returning a Float3, used by uniforms.
Definition: OpenColorIO.h:2810
ImageBuf OIIO_API min(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
class OCIOEXPORT Config
#define OCIO_NAMESPACE
Definition: OpenColorABI.h:8
DynamicPropertyType
Types for dynamic properties.
GLenum GLenum GLsizei const GLuint GLboolean enabled
Definition: glcorearb.h:2539
GLuint const GLchar * name
Definition: glcorearb.h:786
OCIOEXPORT void LogMessage(LoggingLevel level, const char *message)
Log a message using the library logging function.
class OCIOEXPORT Exception
class OCIOEXPORT Look
OCIOEXPORT int GetVersionHex()
Get the version number for the library, as a single 4-byte hex number (e.g., 0x01050200 for "1...
OCIO_SHARED_PTR< const NamedTransform > ConstNamedTransformRcPtr
static const char * FilePathSearchRuleName
Reserved rule name for the file path search rule.
Definition: OpenColorIO.h:1210
std::function< const int *()> VectorIntGetter
Function returning an int *, used by uniforms.
Definition: OpenColorIO.h:2816
GLenum GLsizei GLsizei GLint * values
Definition: glcorearb.h:1602
OCIOEXPORT void ClearAllCaches()
GpuLanguage
Used when there is a choice of hardware shader language.
ProcessorCacheFlags
cpp:type:: Enum to control the behavior of the internal caches e.g. the processor cache in ...
GLuint GLenum GLenum transform
Definition: glew.h:15055
OCIO_SHARED_PTR< Look > LookRcPtr
bool operator==(const BaseDimensions< T > &a, const BaseDimensions< Y > &b)
Definition: Dimensions.h:137
OCIO_SHARED_PTR< const ProcessorMetadata > ConstProcessorMetadataRcPtr
class OCIOEXPORT GpuShaderCreator
OCIO_SHARED_PTR< const Context > ConstContextRcPtr
class OCIOEXPORT Context
class OCIOEXPORT CPUProcessor
OCIO_SHARED_PTR< ProcessorMetadata > ProcessorMetadataRcPtr
OCIO_SHARED_PTR< const CPUProcessor > ConstCPUProcessorRcPtr
OCIOEXPORT void SetLoggingFunction(LoggingFunction logFunction)
Set the logging function to use; otherwise, use the default (i.e. std::cerr).
OCIOEXPORT void ResetToDefaultLoggingFunction()
class OCIOEXPORT ViewTransform
OCIO_SHARED_PTR< Baker > BakerRcPtr
OCIOEXPORT const char * GetEnvVariable(const char *name)
class OCIOEXPORT ProcessorMetadata
GLuint GLuint end
Definition: glcorearb.h:475
A config defines all the color spaces to be available at runtime.
Definition: OpenColorIO.h:236
class OCIOEXPORT GPUProcessor
OPENVDB_API void setVersion(std::ios_base &, const VersionId &libraryVersion, uint32_t fileVersion)
Associate specific file format and library version numbers with the given stream. ...
std::function< void(const char *)> LoggingFunction
Define the logging function signature.
std::function< double()> DoubleGetter
Function returning a double, used by uniforms. GPU converts double to float.
Definition: OpenColorIO.h:2806
#define OCIOEXPORT
Definition: OpenColorABI.h:67
OCIOEXPORT void SetEnvVariable(const char *name, const char *value)
OCIO_SHARED_PTR< const Processor > ConstProcessorRcPtr
OCIO_SHARED_PTR< const ColorSpaceSet > ConstColorSpaceSetRcPtr
OCIO_SHARED_PTR< const FileRules > ConstFileRulesRcPtr
GLbitfield flags
Definition: glcorearb.h:1596
#define OCIO_DEPRECATED(msg)
Definition: OpenColorABI.h:38
class OCIOEXPORT Baker
GLint GLsizei width
Definition: glcorearb.h:103
OCIOEXPORT void ResetComputeHashFunction()
GLint GLsizei GLsizei height
Definition: glcorearb.h:103
OCIOEXPORT const char * GetVersion()
Get the version number for the library, as a dot-delimited string (e.g., "1.0.0").
UniformDataType
Types for uniform data.
GLenum mode
Definition: glcorearb.h:99
std::function< std::string(const std::string &)> ComputeHashFunction
Define Compute Hash function signature.
GLubyte * pattern
Definition: glew.h:5741
OCIO_SHARED_PTR< const SystemMonitors > ConstSystemMonitorsRcPtr
std::function< bool()> BoolGetter
Function returning a bool, used by uniforms.
Definition: OpenColorIO.h:2808
OCIO_SHARED_PTR< ColorSpaceSet > ColorSpaceSetRcPtr
OCIO_SHARED_PTR< const Config > ConstConfigRcPtr
OCIO_SHARED_PTR< NamedTransform > NamedTransformRcPtr
OCIOEXPORT ConstColorSpaceSetRcPtr operator&&(const ConstColorSpaceSetRcPtr &lcss, const ConstColorSpaceSetRcPtr &rcss)
Perform the intersection of two sets.
OCIO_SHARED_PTR< const Look > ConstLookRcPtr
class OCIOEXPORT Processor
class OCIOEXPORT ImageDesc
OCIO_SHARED_PTR< Config > ConfigRcPtr
GLuint index
Definition: glcorearb.h:786
class OCIOEXPORT NamedTransform
OCIO_SHARED_PTR< Context > ContextRcPtr
OCIOEXPORT void SetCurrentConfig(const ConstConfigRcPtr &config)
Set the current configuration. This will then store a copy of the specified config.
OCIOEXPORT std::ostream & operator<<(std::ostream &, const ColorSpaceMenuParameters &)
Definition: core.h:982
OCIO_SHARED_PTR< GpuShaderDesc > GpuShaderDescRcPtr
class OCIOEXPORT FileRules
OCIOEXPORT void UnsetEnvVariable(const char *name)
OCIOEXPORT bool IsEnvVariablePresent(const char *name)
cpp:function::
OCIOEXPORT ConstColorSpaceSetRcPtr operator||(const ConstColorSpaceSetRcPtr &lcss, const ConstColorSpaceSetRcPtr &rcss)
Perform the union of two sets.
class OCIOEXPORT SystemMonitors
Definition: core.h:1131
OCIO_SHARED_PTR< GroupTransform > GroupTransformRcPtr
class OCIOEXPORT ColorSpace
bool operator!=(const BaseDimensions< T > &a, const BaseDimensions< Y > &b)
Definition: Dimensions.h:165
#define const
Definition: zconf.h:214
type
Definition: core.h:1059
const ptrdiff_t AutoStride
Definition: OpenColorIO.h:2487
OCIO_SHARED_PTR< const ViewingRules > ConstViewingRulesRcPtr
OCIO_SHARED_PTR< ColorSpace > ColorSpaceRcPtr
OCIOEXPORT LoggingLevel GetLoggingLevel()
Get the global logging level.
An exception class for errors detected at runtime.
Definition: OpenColorIO.h:96
This class contains meta information about the process that generated this processor. The results of these functions do not impact the pixel processing.
Definition: OpenColorIO.h:2324
OCIO_SHARED_PTR< const ColorSpace > ConstColorSpaceRcPtr
OIIO_UTIL_API std::string extension(string_view filepath, bool include_dot=true) noexcept
OCIO_SHARED_PTR< const GPUProcessor > ConstGPUProcessorRcPtr
Definition: format.h:895
The File Rules are a set of filepath to color space mappings that are evaluated from first to last...
Definition: OpenColorIO.h:1203
OCIO_SHARED_PTR< ViewTransform > ViewTransformRcPtr
OCIO_SHARED_PTR< DynamicProperty > DynamicPropertyRcPtr
PcpNodeRef_ChildrenIterator begin(const PcpNodeRef::child_const_range &r)
Support for range-based for loops for PcpNodeRef children ranges.
Definition: node.h:450