HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
OpenColorIO.h
Go to the documentation of this file.
1 /*
2 Copyright (c) 2003-2010 Sony Pictures Imageworks Inc., et al.
3 All Rights Reserved.
4 
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions are
7 met:
8 * Redistributions of source code must retain the above copyright
9  notice, this list of conditions and the following disclaimer.
10 * Redistributions in binary form must reproduce the above copyright
11  notice, this list of conditions and the following disclaimer in the
12  documentation and/or other materials provided with the distribution.
13 * Neither the name of Sony Pictures Imageworks nor the names of its
14  contributors may be used to endorse or promote products derived from
15  this software without specific prior written permission.
16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28 
29 
30 #ifndef INCLUDED_OCIO_OPENCOLORIO_H
31 #define INCLUDED_OCIO_OPENCOLORIO_H
32 
33 #include <exception>
34 #include <iosfwd>
35 #include <string>
36 #include <cstddef>
37 
38 #include "OpenColorABI.h"
39 #include "OpenColorTypes.h"
40 #include "OpenColorTransforms.h"
41 
42 /*!rst::
43 C++ API
44 =======
45 
46 **Usage Example:** *Compositing plugin that converts from "log" to "lin"*
47 
48 .. code-block:: cpp
49 
50  #include <OpenColorIO/OpenColorIO.h>
51  namespace OCIO = OCIO_NAMESPACE;
52 
53  try
54  {
55  // Get the global OpenColorIO config
56  // This will auto-initialize (using $OCIO) on first use
57  OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig();
58 
59  // Get the processor corresponding to this transform.
60  OCIO::ConstProcessorRcPtr processor = config->getProcessor(OCIO::ROLE_COMPOSITING_LOG,
61  OCIO::ROLE_SCENE_LINEAR);
62 
63  // Wrap the image in a light-weight ImageDescription
64  OCIO::PackedImageDesc img(imageData, w, h, 4);
65 
66  // Apply the color transformation (in place)
67  processor->apply(img);
68  }
69  catch(OCIO::Exception & exception)
70  {
71  std::cerr << "OpenColorIO Error: " << exception.what() << std::endl;
72  }
73 
74 */
75 
77 {
78  ///////////////////////////////////////////////////////////////////////////
79  //!rst::
80  // Exceptions
81  // **********
82 
83  //!cpp:class:: An exception class to throw for errors detected at
84  // runtime.
85  //
86  // .. warning::
87  // All functions in the Config class can potentially throw this exception.
88  class OCIOEXPORT Exception : public std::exception
89  {
90  public:
91  //!cpp:function:: Constructor that takes a string as the exception message.
92  Exception(const char *) throw();
93  //!cpp:function:: Constructor that takes an exception pointer.
94  Exception(const Exception&) throw();
95  //!cpp:function:: Constructor that takes an exception pointer and returns an exception pointer (???).
96  Exception& operator=(const Exception&) throw();
97  //!cpp:function::
98  virtual ~Exception() throw();
99  //!cpp:function::
100  virtual const char* what() const throw();
101 
102  private:
103  //Add pragma warnings, STL member is private and not consumed by client of DLL
104  #ifdef _WIN32
105  #pragma warning(push)
106  #pragma warning(disable:4251)
107  #endif // _WIN32
108 
109  std::string msg_;
110 
111  #ifdef _WIN32
112  #pragma warning(pop)
113  #endif // _WIN32
114  };
115 
116  //!cpp:class:: An exception class for errors detected at
117  // runtime, thrown when OCIO cannot find a file that is expected to
118  // exist. This is provided as a custom type to
119  // distinguish cases where one wants to continue looking for
120  // missing files, but wants to properly fail
121  // for other error conditions.
122 
124  {
125  public:
126  //!cpp:function:: Constructor that takes a string as the exception message.
127  ExceptionMissingFile(const char *) throw();
128  //!cpp:function:: Constructor that takes an existing exception.
130  };
131 
132  ///////////////////////////////////////////////////////////////////////////
133  //!rst::
134  // Global
135  // ******
136 
137  //!cpp:function::
138  // OpenColorIO, during normal usage, tends to cache certain information
139  // (such as the contents of LUTs on disk, intermediate results, etc.).
140  // Calling this function will flush all such information.
141  // Under normal usage, this is not necessary, but it can be helpful in particular instances,
142  // such as designing OCIO profiles, and wanting to re-read luts without
143  // restarting.
144 
145  extern OCIOEXPORT void ClearAllCaches();
146 
147  //!cpp:function:: Get the version number for the library, as a
148  // dot-delimited string (e.g., "1.0.0"). This is also available
149  // at compile time as OCIO_VERSION.
150 
151  extern OCIOEXPORT const char * GetVersion();
152 
153  //!cpp:function:: Get the version number for the library, as a
154  // single 4-byte hex number (e.g., 0x01050200 for "1.5.2"), to be used
155  // for numeric comparisons. This is also available
156  // at compile time as OCIO_VERSION_HEX.
157 
158  extern OCIOEXPORT int GetVersionHex();
159 
160  //!cpp:function:: Get the global logging level.
161  // You can override this at runtime using the :envvar:`OCIO_LOGGING_LEVEL`
162  // environment variable. The client application that sets this should use
163  // :cpp:func:`SetLoggingLevel`, and not the environment variable. The default value is INFO.
164 
166 
167  //!cpp:function:: Set the global logging level.
169 
170 
171  ///////////////////////////////////////////////////////////////////////////
172  //!rst::
173  // Config
174  // ******
175  //
176  // A config defines all the color spaces to be available at runtime.
177  //
178  // The color configuration (:cpp:class:`Config`) is the main object for
179  // interacting with this library. It encapsulates all of the information
180  // necessary to use customized :cpp:class:`ColorSpaceTransform` and
181  // :cpp:class:`DisplayTransform` operations.
182  //
183  // See the :ref:`user-guide` for more information on
184  // selecting, creating, and working with custom color configurations.
185  //
186  // For applications interested in using only one color config at
187  // a time (this is the vast majority of apps), their API would
188  // traditionally get the global configuration and use that, as opposed to
189  // creating a new one. This simplifies the use case for
190  // plugins and bindings, as it alleviates the need to pass around configuration
191  // handles.
192  //
193  // An example of an application where this would not be sufficient would be
194  // a multi-threaded image proxy server (daemon), which wished to handle
195  // multiple show configurations in a single process concurrently. This
196  // app would need to keep multiple configurations alive, and to manage them
197  // appropriately.
198  //
199  // Roughly speaking, a novice user should select a
200  // default configuration that most closely approximates the use case
201  // (animation, visual effects, etc.), and set the :envvar:`OCIO` environment
202  // variable to point at the root of that configuration.
203  //
204  // .. note::
205  // Initialization using environment variables is typically preferable in
206  // a multi-app ecosystem, as it allows all applications to be
207  // consistently configured.
208  //
209  // See :ref:`developers-usageexamples`
210 
211  //!cpp:function:: Get the current configuration.
212 
214 
215  //!cpp:function:: Set the current configuration. This will then store a copy of the specified config.
216  extern OCIOEXPORT void SetCurrentConfig(const ConstConfigRcPtr & config);
217 
218 
219  //!cpp:class::
221  {
222  public:
223 
224  ///////////////////////////////////////////////////////////////////////////
225  //!rst:: .. _cfginit_section:
226  //
227  // Initialization
228  // ^^^^^^^^^^^^^^
229 
230  //!cpp:function:: Constructor a default empty configuration.
231  static ConfigRcPtr Create();
232  //!cpp:function:: Constructor a configuration using the OCIO environmnet variable.
233  static ConstConfigRcPtr CreateFromEnv();
234  //!cpp:function:: Constructor a configuration using a specific config file.
235  static ConstConfigRcPtr CreateFromFile(const char * filename);
236  //!cpp:function::
237  static ConstConfigRcPtr CreateFromStream(std::istream & istream);
238 
239  //!cpp:function::
240  ConfigRcPtr createEditableCopy() const;
241 
242  //!cpp:function::
243  // This will throw an exception if the config is malformed. The most
244  // common error occurs when references are made to colorspaces that do not
245  // exist.
246  void sanityCheck() const;
247 
248  //!cpp:function::
249  const char * getDescription() const;
250  //!cpp:function::
251  void setDescription(const char * description);
252 
253  //!cpp:function::
254  // Returns the string representation of the Config in YAML text form.
255  // This is typically stored on disk in a file with the extension .ocio.
256  void serialize(std::ostream & os) const;
257 
258  //!cpp:function::
259  // This will produce a hash of the all colorspace definitions, etc.
260  // All external references, such as files used in FileTransforms, etc.,
261  // will be incorporated into the cacheID. While the contents of
262  // the files are not read, the file system is queried for relavent
263  // information (mtime, inode) so that the config's cacheID will
264  // change when the underlying luts are updated.
265  // If a context is not provided, the current Context will be used.
266  // If a null context is provided, file references will not be taken into
267  // account (this is essentially a hash of Config::serialize).
268  const char * getCacheID() const;
269  //!cpp:function::
270  const char * getCacheID(const ConstContextRcPtr & context) const;
271 
272  ///////////////////////////////////////////////////////////////////////////
273  //!rst:: .. _cfgresource_section:
274  //
275  // Resources
276  // ^^^^^^^^^
277  // Given a lut src name, where should we find it?
278 
279  //!cpp:function::
280  ConstContextRcPtr getCurrentContext() const;
281 
282  //!cpp:function::
283  void addEnvironmentVar(const char * name, const char * defaultValue);
284  //!cpp:function::
285  int getNumEnvironmentVars() const;
286  //!cpp:function::
287  const char * getEnvironmentVarNameByIndex(int index) const;
288  //!cpp:function::
289  const char * getEnvironmentVarDefault(const char * name) const;
290  //!cpp:function::
291  void clearEnvironmentVars();
292  //!cpp:function::
293  void setEnvironmentMode(EnvironmentMode mode);
294  //!cpp:function::
295  EnvironmentMode getEnvironmentMode() const;
296  //!cpp:function::
297  void loadEnvironment();
298 
299  //!cpp:function::
300  const char * getSearchPath() const;
301  //!cpp:function::
302  void setSearchPath(const char * path);
303 
304  //!cpp:function::
305  const char * getWorkingDir() const;
306  //!cpp:function::
307  void setWorkingDir(const char * dirname);
308 
309  ///////////////////////////////////////////////////////////////////////////
310  //!rst:: .. _cfgcolorspaces_section:
311  //
312  // ColorSpaces
313  // ^^^^^^^^^^^
314 
315  //!cpp:function::
316  int getNumColorSpaces() const;
317  //!cpp:function:: This will null if an invalid index is specified
318  const char * getColorSpaceNameByIndex(int index) const;
319 
320  //!rst::
321  // .. note::
322  // These fcns all accept either a color space OR role name.
323  // (Colorspace names take precedence over roles.)
324 
325  //!cpp:function:: This will return null if the specified name is not
326  // found.
327  ConstColorSpaceRcPtr getColorSpace(const char * name) const;
328  //!cpp:function::
329  int getIndexForColorSpace(const char * name) const;
330 
331  //!cpp:function::
332  // .. note::
333  // If another color space is already registered with the same name,
334  // this will overwrite it. This stores a copy of the specified
335  // color space.
336  void addColorSpace(const ConstColorSpaceRcPtr & cs);
337  //!cpp:function::
338  void clearColorSpaces();
339 
340  //!cpp:function:: Given the specified string, get the longest,
341  // right-most, colorspace substring that appears.
342  //
343  // * If strict parsing is enabled, and no color space is found, return
344  // an empty string.
345  // * If strict parsing is disabled, return ROLE_DEFAULT (if defined).
346  // * If the default role is not defined, return an empty string.
347  const char * parseColorSpaceFromString(const char * str) const;
348 
349  //!cpp:function::
350  bool isStrictParsingEnabled() const;
351  //!cpp:function::
352  void setStrictParsingEnabled(bool enabled);
353 
354  ///////////////////////////////////////////////////////////////////////////
355  //!rst:: .. _cfgroles_section:
356  //
357  // Roles
358  // ^^^^^
359  // A role is like an alias for a colorspace. You can query the colorspace
360  // corresponding to a role using the normal getColorSpace fcn.
361 
362  //!cpp:function::
363  // .. note::
364  // Setting the ``colorSpaceName`` name to a null string unsets it.
365  void setRole(const char * role, const char * colorSpaceName);
366  //!cpp:function::
367  int getNumRoles() const;
368  //!cpp:function:: Return true if the role has been defined.
369  bool hasRole(const char * role) const;
370  //!cpp:function:: Get the role name at index, this will return values
371  // like 'scene_linear', 'compositing_log'.
372  // Return empty string if index is out of range.
373  const char * getRoleName(int index) const;
374 
375 
376 
377  ///////////////////////////////////////////////////////////////////////////
378  //!rst:: .. _cfgdisplayview_section:
379  //
380  // Display/View Registration
381  // ^^^^^^^^^^^^^^^^^^^^^^^^^
382  //
383  // Looks is a potentially comma (or colon) delimited list of lookNames,
384  // Where +/- prefixes are optionally allowed to denote forward/inverse
385  // look specification. (And forward is assumed in the absence of either)
386 
387  //!cpp:function::
388  const char * getDefaultDisplay() const;
389  //!cpp:function::
390  int getNumDisplays() const;
391  //!cpp:function::
392  const char * getDisplay(int index) const;
393 
394  //!cpp:function::
395  const char * getDefaultView(const char * display) const;
396  //!cpp:function::
397  int getNumViews(const char * display) const;
398  //!cpp:function::
399  const char * getView(const char * display, int index) const;
400 
401  //!cpp:function::
402  const char * getDisplayColorSpaceName(const char * display, const char * view) const;
403  //!cpp:function::
404  const char * getDisplayLooks(const char * display, const char * view) const;
405 
406  //!cpp:function:: For the (display,view) combination,
407  // specify which colorSpace and look to use.
408  // If a look is not desired, then just pass an empty string
409 
410  void addDisplay(const char * display, const char * view,
411  const char * colorSpaceName, const char * looks);
412 
413  //!cpp:function::
414  void clearDisplays();
415 
416  // $OCIO_ACTIVE_DISPLAYS envvar can, at runtime, optionally override the allowed displays.
417  // It is a comma or colon delimited list.
418  // Active displays that are not in the specified profile will be ignored, and the
419  // left-most defined display will be the default.
420 
421  //!cpp:function:: Comma-delimited list of display names.
422  void setActiveDisplays(const char * displays);
423  //!cpp:function::
424  const char * getActiveDisplays() const;
425 
426  // $OCIO_ACTIVE_VIEWS envvar can, at runtime, optionally override the allowed views.
427  // It is a comma or colon delimited list.
428  // Active views that are not in the specified profile will be ignored, and the
429  // left-most defined view will be the default.
430 
431  //!cpp:function:: Comma-delimited list of view names.
432  void setActiveViews(const char * views);
433  //!cpp:function::
434  const char * getActiveViews() const;
435 
436 
437  ///////////////////////////////////////////////////////////////////////////
438  //!rst:: .. _cfgluma_section:
439  //
440  // Luma
441  // ^^^^
442  //
443  // Get the default coefficients for computing luma.
444  //
445  // .. note::
446  // There is no "1 size fits all" set of luma coefficients. (The
447  // values are typically different for each colorspace, and the
448  // application of them may be nonsensical depending on the
449  // intensity coding anyways). Thus, the 'right' answer is to make
450  // these functions on the :cpp:class:`Config` class. However, it's
451  // often useful to have a config-wide default so here it is. We will
452  // add the colorspace specific luma call if/when another client is
453  // interesting in using it.
454 
455  //!cpp:function::
456  void getDefaultLumaCoefs(float * rgb) const;
457  //!cpp:function:: These should be normalized (sum to 1.0 exactly).
458  void setDefaultLumaCoefs(const float * rgb);
459 
460 
461  ///////////////////////////////////////////////////////////////////////////
462  //!rst:: .. _cflooka_section:
463  //
464  // Look
465  // ^^^^
466  //
467  // Manager per-shot look settings.
468  //
469 
470  //!cpp:function::
471  ConstLookRcPtr getLook(const char * name) const;
472 
473  //!cpp:function::
474  int getNumLooks() const;
475 
476  //!cpp:function::
477  const char * getLookNameByIndex(int index) const;
478 
479  //!cpp:function::
480  void addLook(const ConstLookRcPtr & look);
481 
482  //!cpp:function::
483  void clearLooks();
484 
485 
486  ///////////////////////////////////////////////////////////////////////////
487  //!rst:: .. _cfgprocessors_section:
488  //
489  // Processors
490  // ^^^^^^^^^^
491  //
492  // Convert from inputColorSpace to outputColorSpace
493  //
494  // .. note::
495  // This may provide higher fidelity than anticipated due to internal
496  // optimizations. For example, if the inputcolorspace and the
497  // outputColorSpace are members of the same family, no conversion
498  // will be applied, even though strictly speaking quantization
499  // should be added.
500  //
501  // If you wish to test these calls for quantization characteristics,
502  // apply in two steps; the image must contain RGB triples (though
503  // arbitrary numbers of additional channels can be supported (ignored)
504  // using the pixelStrideBytes arg).
505 
506  //!cpp:function::
507  ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
508  const ConstColorSpaceRcPtr & srcColorSpace,
509  const ConstColorSpaceRcPtr & dstColorSpace) const;
510  //!cpp:function::
511  ConstProcessorRcPtr getProcessor(const ConstColorSpaceRcPtr & srcColorSpace,
512  const ConstColorSpaceRcPtr & dstColorSpace) const;
513 
514  //!cpp:function::
515  // .. note::
516  // Names can be colorspace name, role name, or a combination of both.
517  ConstProcessorRcPtr getProcessor(const char * srcName,
518  const char * dstName) const;
519  //!cpp:function::
520  ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
521  const char * srcName,
522  const char * dstName) const;
523 
524  //!rst:: Get the processor for the specified transform.
525  //
526  // Not often needed, but will allow for the re-use of atomic OCIO
527  // functionality (such as to apply an individual LUT file).
528 
529  //!cpp:function::
530  ConstProcessorRcPtr getProcessor(const ConstTransformRcPtr& transform) const;
531  //!cpp:function::
532  ConstProcessorRcPtr getProcessor(const ConstTransformRcPtr& transform,
534  //!cpp:function::
535  ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
536  const ConstTransformRcPtr& transform,
537  TransformDirection direction) const;
538 
539  private:
540  Config();
541  ~Config();
542 
543  Config(const Config &);
544  Config& operator= (const Config &);
545 
546  static void deleter(Config* c);
547 
548  class Impl;
549  friend class Impl;
550  Impl * m_impl;
551  Impl * getImpl() { return m_impl; }
552  const Impl * getImpl() const { return m_impl; }
553  };
554 
555  extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Config&);
556 
557 
558  ///////////////////////////////////////////////////////////////////////////
559  //!rst:: .. _colorspace_section:
560  //
561  // ColorSpace
562  // **********
563  // The *ColorSpace* is the state of an image with respect to colorimetry
564  // and color encoding. Transforming images between different
565  // *ColorSpaces* is the primary motivation for this library.
566  //
567  // While a complete discussion of color spaces is beyond the scope of
568  // header documentation, traditional uses would be to have *ColorSpaces*
569  // corresponding to: physical capture devices (known cameras, scanners),
570  // and internal 'convenience' spaces (such as scene linear, logarithmic).
571  //
572  // *ColorSpaces* are specific to a particular image precision (float32,
573  // uint8, etc.), and the set of ColorSpaces that provide equivalent mappings
574  // (at different precisions) are referred to as a 'family'.
575 
576  //!cpp:class::
578  {
579  public:
580  //!cpp:function::
581  static ColorSpaceRcPtr Create();
582 
583  //!cpp:function::
584  ColorSpaceRcPtr createEditableCopy() const;
585 
586  //!cpp:function::
587  const char * getName() const;
588  //!cpp:function::
589  void setName(const char * name);
590 
591  //!cpp:function::Get the family, for use in user interfaces (optional)
592  const char * getFamily() const;
593  //!cpp:function::Set the family, for use in user interfaces (optional)
594  void setFamily(const char * family);
595 
596  //!cpp:function::Get the ColorSpace group name (used for equality comparisons)
597  // This allows no-op transforms between different colorspaces.
598  // If an equalityGroup is not defined (an empty string), it will be considered
599  // unique (i.e., it will not compare as equal to other ColorSpaces with an
600  // empty equality group). This is often, though not always, set to the
601  // same value as 'family'.
602  const char * getEqualityGroup() const;
603  //!cpp:function::
604  void setEqualityGroup(const char * equalityGroup);
605 
606  //!cpp:function::
607  const char * getDescription() const;
608  //!cpp:function::
609  void setDescription(const char * description);
610 
611  //!cpp:function::
612  BitDepth getBitDepth() const;
613  //!cpp:function::
614  void setBitDepth(BitDepth bitDepth);
615 
616  ///////////////////////////////////////////////////////////////////////////
617  //!rst::
618  // Data
619  // ^^^^
620  // ColorSpaces that are data are treated a bit special. Basically, any
621  // colorspace transforms you try to apply to them are ignored. (Think
622  // of applying a gamut mapping transform to an ID pass). Also, the
623  // :cpp:class:`DisplayTransform` process obeys special 'data min' and
624  // 'data max' args.
625  //
626  // This is traditionally used for pixel data that represents non-color
627  // pixel data, such as normals, point positions, ID information, etc.
628 
629  //!cpp:function::
630  bool isData() const;
631  //!cpp:function::
632  void setIsData(bool isData);
633 
634  ///////////////////////////////////////////////////////////////////////////
635  //!rst::
636  // Allocation
637  // ^^^^^^^^^^
638  // If this colorspace needs to be transferred to a limited dynamic
639  // range coding space (such as during display with a GPU path), use this
640  // allocation to maximize bit efficiency.
641 
642  //!cpp:function::
643  Allocation getAllocation() const;
644  //!cpp:function::
645  void setAllocation(Allocation allocation);
646 
647  //!rst::
648  // Specify the optional variable values to configure the allocation.
649  // If no variables are specified, the defaults are used.
650  //
651  // ALLOCATION_UNIFORM::
652  //
653  // 2 vars: [min, max]
654  //
655  // ALLOCATION_LG2::
656  //
657  // 2 vars: [lg2min, lg2max]
658  // 3 vars: [lg2min, lg2max, linear_offset]
659 
660  //!cpp:function::
661  int getAllocationNumVars() const;
662  //!cpp:function::
663  void getAllocationVars(float * vars) const;
664  //!cpp:function::
665  void setAllocationVars(int numvars, const float * vars);
666 
667  ///////////////////////////////////////////////////////////////////////////
668  //!rst::
669  // Transform
670  // ^^^^^^^^^
671 
672  //!cpp:function::
673  // If a transform in the specified direction has been specified,
674  // return it. Otherwise return a null ConstTransformRcPtr
675  ConstTransformRcPtr getTransform(ColorSpaceDirection dir) const;
676  //!cpp:function::
677  // Specify the transform for the appropriate direction.
678  // Setting the transform to null will clear it.
679  void setTransform(const ConstTransformRcPtr & transform,
680  ColorSpaceDirection dir);
681 
682  private:
683  ColorSpace();
684  ~ColorSpace();
685 
686  ColorSpace(const ColorSpace &);
687  ColorSpace& operator= (const ColorSpace &);
688 
689  static void deleter(ColorSpace* c);
690 
691  class Impl;
692  friend class Impl;
693  Impl * m_impl;
694  Impl * getImpl() { return m_impl; }
695  const Impl * getImpl() const { return m_impl; }
696  };
697 
698  extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const ColorSpace&);
699 
700 
701 
702 
703 
704 
705 
706  ///////////////////////////////////////////////////////////////////////////
707  //!rst:: .. _look_section:
708  //
709  // Look
710  // ****
711  // The *Look* is an 'artistic' image modification, in a specified image
712  // state.
713  // The processSpace defines the ColorSpace the image is required to be
714  // in, for the math to apply correctly.
715 
716  //!cpp:class::
718  {
719  public:
720  //!cpp:function::
721  static LookRcPtr Create();
722 
723  //!cpp:function::
724  LookRcPtr createEditableCopy() const;
725 
726  //!cpp:function::
727  const char * getName() const;
728  //!cpp:function::
729  void setName(const char * name);
730 
731  //!cpp:function::
732  const char * getProcessSpace() const;
733  //!cpp:function::
734  void setProcessSpace(const char * processSpace);
735 
736  //!cpp:function::
737  ConstTransformRcPtr getTransform() const;
738  //!cpp:function:: Setting a transform to a non-null call makes it allowed.
739  void setTransform(const ConstTransformRcPtr & transform);
740 
741  //!cpp:function::
742  ConstTransformRcPtr getInverseTransform() const;
743  //!cpp:function:: Setting a transform to a non-null call makes it allowed.
744  void setInverseTransform(const ConstTransformRcPtr & transform);
745 
746  //!cpp:function::
747  const char * getDescription() const;
748  //!cpp:function::
749  void setDescription(const char * description);
750  private:
751  Look();
752  ~Look();
753 
754  Look(const Look &);
755  Look& operator= (const Look &);
756 
757  static void deleter(Look* c);
758 
759  class Impl;
760  friend class Impl;
761  Impl * m_impl;
762  Impl * getImpl() { return m_impl; }
763  const Impl * getImpl() const { return m_impl; }
764  };
765 
766  extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Look&);
767 
768 
769  ///////////////////////////////////////////////////////////////////////////
770  //!rst::
771  // Processor
772  // *********
773 
774  //!cpp:class::
776  {
777  public:
778  //!cpp:function::
779  static ProcessorRcPtr Create();
780 
781  //!cpp:function::
782  bool isNoOp() const;
783 
784  //!cpp:function:: does the processor represent an image transformation that
785  // introduces crosstalk between the image channels
786  bool hasChannelCrosstalk() const;
787 
788  //!cpp:function::
789  ConstProcessorMetadataRcPtr getMetadata() const;
790 
791  ///////////////////////////////////////////////////////////////////////////
792  //!rst::
793  // CPU Path
794  // ^^^^^^^^
795 
796  //!cpp:function:: Apply to an image.
797  void apply(ImageDesc& img) const;
798 
799  //!rst::
800  // Apply to a single pixel.
801  //
802  // .. note::
803  // This is not as efficient as applying to an entire image at once.
804  // If you are processing multiple pixels, and have the flexibility,
805  // use the above function instead.
806 
807  //!cpp:function::
808  void applyRGB(float * pixel) const;
809  //!cpp:function::
810  void applyRGBA(float * pixel) const;
811 
812  //!cpp:function::
813  const char * getCpuCacheID() const;
814 
815  ///////////////////////////////////////////////////////////////////////////
816  //!rst::
817  // GPU Path
818  // ^^^^^^^^
819  // Get the 3d lut + cg shader for the specified
820  // :cpp:class:`DisplayTransform`.
821  //
822  // cg signature will be::
823  //
824  // shaderFcnName(in half4 inPixel, const uniform sampler3D lut3d)
825  //
826  // lut3d should be size: 3 * edgeLen * edgeLen * edgeLen
827  // return 0 if unknown
828 
829  //!cpp:function::
830  const char * getGpuShaderText(const GpuShaderDesc & shaderDesc) const;
831  //!cpp:function::
832  const char * getGpuShaderTextCacheID(const GpuShaderDesc & shaderDesc) const;
833 
834  //!cpp:function::
835  void getGpuLut3D(float* lut3d, const GpuShaderDesc & shaderDesc) const;
836  //!cpp:function::
837  const char * getGpuLut3DCacheID(const GpuShaderDesc & shaderDesc) const;
838 
839  private:
840  Processor();
841  ~Processor();
842 
843  Processor(const Processor &);
844  Processor& operator= (const Processor &);
845 
846  static void deleter(Processor* c);
847 
848  friend class Config;
849 
850  class Impl;
851  friend class Impl;
852  Impl * m_impl;
853  Impl * getImpl() { return m_impl; }
854  const Impl * getImpl() const { return m_impl; }
855  };
856 
857 
858  //!cpp:class::
859  // This class contains meta information about the process that generated
860  // this processor. The results of these functions do not
861  // impact the pixel processing.
862 
864  {
865  public:
866  //!cpp:function::
867  static ProcessorMetadataRcPtr Create();
868 
869  //!cpp:function::
870  int getNumFiles() const;
871  //!cpp:function::
872  const char * getFile(int index) const;
873 
874  //!cpp:function::
875  int getNumLooks() const;
876  //!cpp:function::
877  const char * getLook(int index) const;
878 
879  //!cpp:function::
880  void addFile(const char * fname);
881  //!cpp:function::
882  void addLook(const char * look);
883  private:
887  ProcessorMetadata& operator= (const ProcessorMetadata &);
888 
889  static void deleter(ProcessorMetadata* c);
890 
891  class Impl;
892  friend class Impl;
893  Impl * m_impl;
894  Impl * getImpl() { return m_impl; }
895  const Impl * getImpl() const { return m_impl; }
896  };
897 
898 
899 
900  ///////////////////////////////////////////////////////////////////////////
901  //!rst::
902  // Baker
903  // *****
904  //
905  // In certain situations it is necessary to serialize transforms into a variety
906  // of application specific lut formats. The Baker can be used to create lut
907  // formats that ocio supports for writing.
908  //
909  // **Usage Example:** *Bake a houdini sRGB viewer lut*
910  //
911  // .. code-block:: cpp
912  //
913  // OCIO::ConstConfigRcPtr config = OCIO::Config::CreateFromEnv();
914  // OCIO::BakerRcPtr baker = OCIO::Baker::Create();
915  // baker->setConfig(config);
916  // baker->setFormat("houdini"); // set the houdini type
917  // baker->setType("3D"); // we want a 3D lut
918  // baker->setInputSpace("lnf");
919  // baker->setShaperSpace("log");
920  // baker->setTargetSpace("sRGB");
921  // std::ostringstream out;
922  // baker->bake(out); // fresh bread anyone!
923  // std::cout << out.str();
924 
926  {
927  public:
928  //!cpp:function:: create a new Baker
929  static BakerRcPtr Create();
930 
931  //!cpp:function:: create a copy of this Baker
932  BakerRcPtr createEditableCopy() const;
933 
934  //!cpp:function:: set the config to use
935  void setConfig(const ConstConfigRcPtr & config);
936  //!cpp:function:: get the config to use
937  ConstConfigRcPtr getConfig() const;
938 
939  //!cpp:function:: set the lut output format
940  void setFormat(const char * formatName);
941  //!cpp:function:: get the lut output format
942  const char * getFormat() const;
943 
944  // TODO: Change this to an enum
945  //!cpp:function:: set the lut output type (1D or 3D)
946  void setType(const char * type);
947  //!cpp:function:: get the lut output type
948  const char * getType() const;
949 
950  //!cpp:function:: set *optional* meta data for luts that support it
951  void setMetadata(const char * metadata);
952  //!cpp:function:: get the meta data that has been set
953  const char * getMetadata() const;
954 
955  //!cpp:function:: set the input ColorSpace that the lut will be
956  // applied to
957  void setInputSpace(const char * inputSpace);
958  //!cpp:function:: get the input ColorSpace that has been set
959  const char * getInputSpace() const;
960 
961  //!cpp:function:: set an *optional* ColorSpace to be used to shape /
962  // transfer the input colorspace. This is mostly used to allocate
963  // an HDR luminance range into an LDR one. If a shaper space
964  // is not explicitly specified, and the file format supports one,
965  // the ColorSpace Allocation will be used
966 
967  void setShaperSpace(const char * shaperSpace);
968  //!cpp:function:: get the shaper colorspace that has been set
969  const char * getShaperSpace() const;
970 
971  //!cpp:function:: set the looks to be applied during baking
972  // Looks is a potentially comma (or colon) delimited list of lookNames,
973  // Where +/- prefixes are optionally allowed to denote forward/inverse
974  // look specification. (And forward is assumed in the absence of either)
975  void setLooks(const char * looks);
976  //!cpp:function:: get the looks to be applied during baking
977  const char * getLooks() const;
978 
979  //!cpp:function:: set the target device colorspace for the lut
980  void setTargetSpace(const char * targetSpace);
981  //!cpp:function:: get the target colorspace that has been set
982  const char * getTargetSpace() const;
983 
984  //!cpp:function:: override the default the shaper sample size,
985  // default: <format specific>
986  void setShaperSize(int shapersize);
987  //!cpp:function:: get the shaper sample size
988  int getShaperSize() const;
989 
990  //!cpp:function:: override the default cube sample size
991  // default: <format specific>
992  void setCubeSize(int cubesize);
993  //!cpp:function:: get the cube sample size
994  int getCubeSize() const;
995 
996  //!cpp:function:: bake the lut into the output stream
997  void bake(std::ostream & os) const;
998 
999  //!cpp:function:: get the number of lut writers
1000  static int getNumFormats();
1001 
1002  //!cpp:function:: get the lut writer at index, return empty string if
1003  // an invalid index is specified
1004  static const char * getFormatNameByIndex(int index);
1005  static const char * getFormatExtensionByIndex(int index);
1006 
1007  private:
1008  Baker();
1009  ~Baker();
1010 
1011  Baker(const Baker &);
1012  Baker& operator= (const Baker &);
1013 
1014  static void deleter(Baker* o);
1015 
1016  class Impl;
1017  friend class Impl;
1018  Impl * m_impl;
1019  Impl * getImpl() { return m_impl; }
1020  const Impl * getImpl() const { return m_impl; }
1021  };
1022 
1023 
1024  ///////////////////////////////////////////////////////////////////////////
1025  //!rst::
1026  // ImageDesc
1027  // *********
1028 
1029  //!rst::
1030  // .. c:var:: const ptrdiff_t AutoStride
1031  //
1032  // AutoStride
1034 
1035  //!cpp:class::
1036  // This is a light-weight wrapper around an image, that provides a context
1037  // for pixel access. This does NOT claim ownership of the pixels or copy
1038  // image data
1039 
1041  {
1042  public:
1043  //!cpp:function::
1044  virtual ~ImageDesc();
1045  private:
1046  ImageDesc& operator= (const ImageDesc &);
1047  };
1048 
1049  extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const ImageDesc&);
1050 
1051 
1052  ///////////////////////////////////////////////////////////////////////////
1053  //!rst::
1054  // PackedImageDesc
1055  // ^^^^^^^^^^^^^^^
1056 
1057  //!cpp:class::
1059  {
1060  public:
1061  //!cpp:function::
1062  // Pass the pointer to packed image data: rgbrgbrgb, etc.
1063  // The number of channels must be greater than or equal to 3
1064  // If a 4th channel is specified, it is assumed to be alpha
1065  // information. Channels > 4 will be ignored.
1066 
1067  PackedImageDesc(float * data,
1068  long width, long height,
1069  long numChannels,
1070  ptrdiff_t chanStrideBytes = AutoStride,
1071  ptrdiff_t xStrideBytes = AutoStride,
1072  ptrdiff_t yStrideBytes = AutoStride);
1073  //!cpp:function::
1074  virtual ~PackedImageDesc();
1075 
1076  //!cpp:function::
1077  float * getData() const;
1078 
1079  //!cpp:function::
1080  long getWidth() const;
1081  //!cpp:function::
1082  long getHeight() const;
1083  //!cpp:function::
1084  long getNumChannels() const;
1085 
1086  //!cpp:function::
1087  ptrdiff_t getChanStrideBytes() const;
1088  //!cpp:function::
1089  ptrdiff_t getXStrideBytes() const;
1090  //!cpp:function::
1091  ptrdiff_t getYStrideBytes() const;
1092 
1093  private:
1094  class Impl;
1095  friend class Impl;
1096  Impl * m_impl;
1097  Impl * getImpl() { return m_impl; }
1098  const Impl * getImpl() const { return m_impl; }
1099 
1101  PackedImageDesc& operator= (const PackedImageDesc &);
1102  };
1103 
1104 
1105  ///////////////////////////////////////////////////////////////////////////
1106  //!rst::
1107  // PlanarImageDesc
1108  // ^^^^^^^^^^^^^^^
1109 
1110  //!cpp:class::
1112  {
1113  public:
1114  //!cpp:function::
1115  // Pass the pointer to the specified image planes: rrrr gggg bbbb, etc.
1116  // aData is optional, pass NULL if no alpha exists.
1117  // {r,g,b} Data must be specified
1118 
1119  PlanarImageDesc(float * rData, float * gData, float * bData, float * aData,
1120  long width, long height,
1121  ptrdiff_t yStrideBytes = AutoStride);
1122  //!cpp:function::
1123  virtual ~PlanarImageDesc();
1124 
1125  //!cpp:function::
1126  float* getRData() const;
1127  //!cpp:function::
1128  float* getGData() const;
1129  //!cpp:function::
1130  float* getBData() const;
1131  //!cpp:function::
1132  float* getAData() const;
1133 
1134  //!cpp:function::
1135  long getWidth() const;
1136  //!cpp:function::
1137  long getHeight() const;
1138 
1139  //!cpp:function::
1140  ptrdiff_t getYStrideBytes() const;
1141 
1142  private:
1143  class Impl;
1144  friend class Impl;
1145  Impl * m_impl;
1146  Impl * getImpl() { return m_impl; }
1147  const Impl * getImpl() const { return m_impl; }
1148 
1150  PlanarImageDesc& operator= (const PlanarImageDesc &);
1151  };
1152 
1153 
1154  ///////////////////////////////////////////////////////////////////////////
1155  //!rst::
1156  // GpuShaderDesc
1157  // *************
1158 
1159  //!cpp:class::
1161  {
1162  public:
1163  //!cpp:function::
1164  GpuShaderDesc();
1165  //!cpp:function::
1166  ~GpuShaderDesc();
1167 
1168  //!cpp:function:: Set the shader program language
1169  void setLanguage(GpuLanguage lang);
1170  //!cpp:function::
1171  GpuLanguage getLanguage() const;
1172 
1173  //!cpp:function:: Set the function name of the shader program
1174  void setFunctionName(const char * name);
1175  //!cpp:function::
1176  const char * getFunctionName() const;
1177 
1178  //!cpp:function::
1179  void setLut3DEdgeLen(int len);
1180  //!cpp:function::
1181  int getLut3DEdgeLen() const;
1182 
1183  //!cpp:function::
1184  const char * getCacheID() const;
1185 
1186  private:
1187 
1188  GpuShaderDesc(const GpuShaderDesc &);
1189  GpuShaderDesc& operator= (const GpuShaderDesc &);
1190 
1191  class Impl;
1192  friend class Impl;
1193  Impl * m_impl;
1194  Impl * getImpl() { return m_impl; }
1195  const Impl * getImpl() const { return m_impl; }
1196  };
1197 
1198 
1199  ///////////////////////////////////////////////////////////////////////////
1200  //!rst::
1201  // Context
1202  // *******
1203 
1204  //!cpp:class::
1206  {
1207  public:
1208  //!cpp:function::
1209  static ContextRcPtr Create();
1210 
1211  //!cpp:function::
1212  ContextRcPtr createEditableCopy() const;
1213 
1214  //!cpp:function::
1215  const char * getCacheID() const;
1216 
1217  //!cpp:function::
1218  void setSearchPath(const char * path);
1219  //!cpp:function::
1220  const char * getSearchPath() const;
1221 
1222  //!cpp:function::
1223  void setWorkingDir(const char * dirname);
1224  //!cpp:function::
1225  const char * getWorkingDir() const;
1226 
1227  //!cpp:function::
1228  void setStringVar(const char * name, const char * value);
1229  //!cpp:function::
1230  const char * getStringVar(const char * name) const;
1231 
1232  //!cpp:function::
1233  int getNumStringVars() const;
1234  //!cpp:function::
1235  const char * getStringVarNameByIndex(int index) const;
1236 
1237  //!cpp:function::
1238  void clearStringVars();
1239 
1240  //!cpp:function::
1241  void setEnvironmentMode(EnvironmentMode mode);
1242 
1243  //!cpp:function::
1244  EnvironmentMode getEnvironmentMode() const;
1245 
1246  //!cpp:function:: Seed all string vars with the current environment.
1247  void loadEnvironment();
1248 
1249  //! Do a string lookup.
1250  //!cpp:function:: Do a file lookup.
1251  //
1252  // Evaluate the specified variable (as needed). Will not throw exceptions.
1253  const char * resolveStringVar(const char * val) const;
1254 
1255  //! Do a file lookup.
1256  //!cpp:function:: Do a file lookup.
1257  //
1258  // Evaluate all variables (as needed).
1259  // Also, walk the full search path until the file is found.
1260  // If the filename cannot be found, an exception will be thrown.
1261  const char * resolveFileLocation(const char * filename) const;
1262 
1263  private:
1264  Context();
1265  ~Context();
1266 
1267  Context(const Context &);
1268  Context& operator= (const Context &);
1269 
1270  static void deleter(Context* c);
1271 
1272  class Impl;
1273  friend class Impl;
1274  Impl * m_impl;
1275  Impl * getImpl() { return m_impl; }
1276  const Impl * getImpl() const { return m_impl; }
1277  };
1278 
1279  extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Context&);
1280 }
1282 
1283 #endif // INCLUDED_OCIO_OPENCOLORIO_H
rst::
Definition: OpenColorIO.h:88
rst:: .. _colorspace_section:
Definition: OpenColorIO.h:577
rst::
Definition: OpenColorIO.h:925
const ptrdiff_t AutoStride
rst::
Definition: OpenColorIO.h:1033
class OCIOEXPORT Context
TransformDirection
cpp:type::
ColorSpaceDirection
cpp:type::
GT_API const UT_StringHolder filename
OCIOEXPORT std::ostream & operator<<(std::ostream &, const Config &)
OCIOEXPORT int GetVersionHex()
cpp:function:: Get the version number for the library, as a
GLuint const GLchar * name
Definition: glew.h:1814
OCIO_SHARED_PTR< Context > ContextRcPtr
cpp:type::
GLenum mode
Definition: glew.h:2163
OCIO_SHARED_PTR< const Processor > ConstProcessorRcPtr
cpp:type::
GLint GLint GLint GLint GLint GLint GLsizei width
Definition: glew.h:1252
GLuint GLenum GLenum transform
Definition: glew.h:14742
GLuint index
Definition: glew.h:1814
OCIOEXPORT LoggingLevel GetLoggingLevel()
cpp:function:: Get the global logging level.
IMF_EXPORT IMATH_NAMESPACE::V3f direction(const IMATH_NAMESPACE::Box2i &dataWindow, const IMATH_NAMESPACE::V2f &pixelPosition)
GLuint const GLfloat * val
Definition: glew.h:2794
rst::
Definition: OpenColorIO.h:775
GLint GLint GLint GLint GLint GLint GLsizei GLsizei height
Definition: glew.h:1252
#define OCIO_NAMESPACE_ENTER
Definition: OpenColorABI.h:49
cpp:class::
Definition: OpenColorIO.h:863
LoggingLevel
rst::
cpp:class::
Definition: OpenColorIO.h:1040
OCIOEXPORT void ClearAllCaches()
rst::
OCIO_SHARED_PTR< Baker > BakerRcPtr
cpp:type::
class OCIOEXPORT ProcessorMetadata
GLint void * img
Definition: glew.h:1385
GLuint srcName
Definition: wglew.h:937
OCIO_SHARED_PTR< ColorSpace > ColorSpaceRcPtr
cpp:type::
class OCIOEXPORT GpuShaderDesc
cpp:class::
Definition: OpenColorIO.h:220
OCIO_SHARED_PTR< const Config > ConstConfigRcPtr
cpp:type::
GLenum GLint GLint GLint GLint GLuint dstName
Definition: glew.h:3901
GLint GLenum GLsizei GLint GLsizei const void * data
Definition: glew.h:1379
class OCIOEXPORT Processor
OCIO_SHARED_PTR< const Transform > ConstTransformRcPtr
cpp:type::
rst:: .. _look_section:
Definition: OpenColorIO.h:717
const GLfloat * c
Definition: glew.h:16296
GpuLanguage
cpp:type:: Used when there is a choice of hardware shader language.
#define OCIOEXPORT
Definition: OpenColorABI.h:97
BitDepth
cpp:type::
cpp:class:: An exception class for errors detected at
Definition: OpenColorIO.h:123
class OCIOEXPORT Look
OCIO_SHARED_PTR< Config > ConfigRcPtr
cpp:type::
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
class OCIOEXPORT Exception
OCIOEXPORT void SetLoggingLevel(LoggingLevel level)
cpp:function:: Set the global logging level.
OCIOEXPORT ConstConfigRcPtr GetCurrentConfig()
rst::
#define OCIO_NAMESPACE_EXIT
Definition: OpenColorABI.h:50
OCIO_SHARED_PTR< Look > LookRcPtr
cpp:type::
Allocation
cpp:type::
GLsizei const GLchar *const * path
Definition: glew.h:6461
GLsizei const GLchar *const * string
Definition: glew.h:1844
OCIO_SHARED_PTR< const Context > ConstContextRcPtr
cpp:type::
GLenum GLsizei const GLuint GLboolean enabled
Definition: glew.h:2579
OCIO_SHARED_PTR< const Look > ConstLookRcPtr
cpp:type::
OCIO_SHARED_PTR< const ProcessorMetadata > ConstProcessorMetadataRcPtr
cpp:type::
class OCIOEXPORT Baker
rst::
Definition: OpenColorIO.h:1205
OCIOEXPORT const char * GetVersion()
cpp:function:: Get the version number for the library, as a
EnvironmentMode
cpp:type::
OCIO_SHARED_PTR< const ColorSpace > ConstColorSpaceRcPtr
cpp:type::
vint4 min(const vint4 &a, const vint4 &b)
Definition: simd.h:4694
OCIOEXPORT void SetCurrentConfig(const ConstConfigRcPtr &config)
cpp:function:: Set the current configuration. This will then store a copy of the specified config...
OCIO_SHARED_PTR< Processor > ProcessorRcPtr
cpp:type::
GLsizei const GLfloat * value
Definition: glew.h:1849
GLint level
Definition: glew.h:1252
class OCIOEXPORT ColorSpace
OCIO_SHARED_PTR< ProcessorMetadata > ProcessorMetadataRcPtr
cpp:type::
GLenum GLsizei len
Definition: glew.h:7752