/export/OpenColorIO/OpenColorIO.h

http://github.com/imageworks/OpenColorIO · C Header · 1268 lines · 396 code · 226 blank · 646 comment · 0 complexity · 7283137c7876cf1e5fcab7c3a2ec20d5 MD5 · raw file

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