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 76 OCIO_NAMESPACE_ENTER 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 123 class OCIOEXPORT ExceptionMissingFile : public Exception 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. 129 ExceptionMissingFile(const ExceptionMissingFile&) throw(); 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 165 extern OCIOEXPORT LoggingLevel GetLoggingLevel(); 166 167 //!cpp:function:: Set the global logging level. 168 extern OCIOEXPORT void SetLoggingLevel(LoggingLevel 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 213 extern OCIOEXPORT ConstConfigRcPtr GetCurrentConfig(); 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:: 220 class OCIOEXPORT Config 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, 533 TransformDirection direction) const; 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; getImpl()551 Impl * getImpl() { return m_impl; } getImpl()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:: 577 class OCIOEXPORT ColorSpace 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; getImpl()694 Impl * getImpl() { return m_impl; } getImpl()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:: 717 class OCIOEXPORT Look 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; getImpl()762 Impl * getImpl() { return m_impl; } getImpl()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:: 775 class OCIOEXPORT Processor 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; getImpl()853 Impl * getImpl() { return m_impl; } getImpl()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 863 class OCIOEXPORT ProcessorMetadata 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: 884 ProcessorMetadata(); 885 ~ProcessorMetadata(); 886 ProcessorMetadata(const ProcessorMetadata &); 887 ProcessorMetadata& operator= (const ProcessorMetadata &); 888 889 static void deleter(ProcessorMetadata* c); 890 891 class Impl; 892 friend class Impl; 893 Impl * m_impl; getImpl()894 Impl * getImpl() { return m_impl; } getImpl()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 925 class OCIOEXPORT Baker 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; getImpl()1019 Impl * getImpl() { return m_impl; } getImpl()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 1033 const ptrdiff_t AutoStride = std::numeric_limits<ptrdiff_t>::min(); 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 1040 class OCIOEXPORT ImageDesc 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:: 1058 class OCIOEXPORT PackedImageDesc : public ImageDesc 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; getImpl()1097 Impl * getImpl() { return m_impl; } getImpl()1098 const Impl * getImpl() const { return m_impl; } 1099 1100 PackedImageDesc(const PackedImageDesc &); 1101 PackedImageDesc& operator= (const PackedImageDesc &); 1102 }; 1103 1104 1105 /////////////////////////////////////////////////////////////////////////// 1106 //!rst:: 1107 // PlanarImageDesc 1108 // ^^^^^^^^^^^^^^^ 1109 1110 //!cpp:class:: 1111 class OCIOEXPORT PlanarImageDesc : public ImageDesc 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; getImpl()1146 Impl * getImpl() { return m_impl; } getImpl()1147 const Impl * getImpl() const { return m_impl; } 1148 1149 PlanarImageDesc(const PlanarImageDesc &); 1150 PlanarImageDesc& operator= (const PlanarImageDesc &); 1151 }; 1152 1153 1154 /////////////////////////////////////////////////////////////////////////// 1155 //!rst:: 1156 // GpuShaderDesc 1157 // ************* 1158 1159 //!cpp:class:: 1160 class OCIOEXPORT GpuShaderDesc 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; getImpl()1194 Impl * getImpl() { return m_impl; } getImpl()1195 const Impl * getImpl() const { return m_impl; } 1196 }; 1197 1198 1199 /////////////////////////////////////////////////////////////////////////// 1200 //!rst:: 1201 // Context 1202 // ******* 1203 1204 //!cpp:class:: 1205 class OCIOEXPORT Context 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; getImpl()1275 Impl * getImpl() { return m_impl; } getImpl()1276 const Impl * getImpl() const { return m_impl; } 1277 }; 1278 1279 extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Context&); 1280 } 1281 OCIO_NAMESPACE_EXIT 1282 1283 #endif // INCLUDED_OCIO_OPENCOLORIO_H 1284